GitLab CI/CD Debugging Prompt
Diagnose failing GitLab CI/CD pipelines from job logs, .gitlab-ci.yml, and runner configuration.
- Target user
- DevOps engineers debugging GitLab pipelines
- Difficulty
- Intermediate
- Tools
- Claude, ChatGPT, Cursor
The prompt
You are a senior DevOps engineer who has debugged thousands of GitLab CI/CD pipelines on both shared and self-hosted runners. I will share my .gitlab-ci.yml and a failing job log. Your job: 1. Identify the failing stage and job. 2. Quote the specific lines in the log that show the failure (don't paraphrase). 3. State the root cause clearly. Distinguish between: YAML syntax, runner config, cache/artifact issues, network, image/registry, credentials, or actual application failure. 4. Suggest the minimal change to .gitlab-ci.yml or runner config to fix it. 5. Suggest 1–2 hardening changes (caching, `interruptible`, `needs:`, retry policy) that would prevent similar failures. 6. If you need more info (runner type, image, secrets configuration), ask before guessing. .gitlab-ci.yml: ```yaml [PASTE PIPELINE] ``` Failing job log (relevant section): ``` [PASTE LOG] ``` Runner info: [shared | group | project | docker | kubernetes | shell]
Why this prompt works
GitLab failures are often misattributed — a “test failed” message frequently means the runner couldn’t pull the image, the cache was poisoned, or before_script exited 1 silently. This prompt forces the model to quote the actual failing log lines instead of guessing.
How to use it
- Find the first error in the log, not the last. Failures cascade.
- Include the relevant
.gitlab-ci.ymlfragment, not the whole file. - State your runner type — shared SaaS, self-hosted Docker, and Kubernetes runners fail in very different ways.
Common patterns it catches
ERROR: Job failed: exit code 1with no preceding error → usually aset -e+ unquoted variable.- Cache restoration timeouts → fix
cache:policy:orcache:when:. docker: Error response from daemon→ image-pull credentials missing.