Fix: GitLab CI Pipeline Stuck in Pending State

!Symptoms

• Pipeline jobs show 'pending' indefinitely
• No runner picks up the job
• Other pipelines/projects work fine
• Runner is registered and shows as online

?Root Causes

• Runner tags don't match the job's tags requirement
• Runner is locked to a different project
• All runners are busy with other jobs
• Runner's executor configuration doesn't match job requirements
• Protected branch/tag settings restricting which runners can execute

#Diagnosis Steps

1. 1Check job tags: CI/CD → Pipelines → Click job → Check tags required
2. 2Check available runners: Settings → CI/CD → Runners — verify tags match
3. 3Check runner status: `gitlab-runner list` and `gitlab-runner verify`
4. 4Check if runner is locked: Settings → CI/CD → Runners → Edit → Lock to current projects
5. 5Check runner logs: `journalctl -u gitlab-runner`

>Fix

1. 1Fix tags in .gitlab-ci.yml to match available runner tags
2. 2Unlock the runner or register a new runner for the project
3. 3Add more runners to handle concurrent jobs
4. 4Remove tags requirement if the job doesn't need specific runners
5. 5For protected branches, ensure runner is allowed to run on protected refs

*Prevention

• Document runner tags and their meanings in the project README
• Use shared runners for common jobs, specific runners only when needed
• Set up autoscaling runners (Docker Machine, Kubernetes executor) for elasticity
• Monitor runner queue depth and alert when jobs are pending too long
• Include runner tag validation in CI lint step

Related Error Messages