GitLab CI YAML is one of those formats where you can stare at it for an hour, get it 95% right, and have it fail with yaml: line 12: did not find expected key
because of a tab character. AI assistants are very fast at this kind of work. They're also confidently wrong about specific GitLab features in ways that waste a lot of time if you don't know what to check.
After a year of letting Claude write a lot of my pipelines, here's what works and what doesn't.
"Write me a job that builds a Docker image, pushes to the GitLab Container Registry, and tags with the commit SHA and latest
on the default branch." Type that into Claude and you get a working job in five seconds. The shape is well-established and the model has seen thousands of variations.
The same is true for:
rules:
for branch / tag / MR pipelinesIf you find yourself writing one of these from scratch, you're spending time that you don't need to spend.
GitLab CI has obvious parallels to GitHub Actions, CircleCI, Jenkins declarative pipelines, etc. AI is excellent at translating between them. The structures rhyme; the model knows the dictionary.
If you're migrating from Actions to GitLab CI, paste the workflow and ask for the GitLab CI equivalent. You'll get something 80% right that you can refine.
This is the underrated use case. Paste your .gitlab-ci.yml
and ask: "what's the critical path of this pipeline, and what's making it slow?" The model will spot things like:
needs:
."rules:changes:
doesn't include package-lock.json
, so dependency changes don't retrigger tests."These are real findings I've gotten from Claude on pipelines I thought I'd already optimized. Worth the five-minute review.
rules:
vs only/except
confusion
The model will sometimes mix them in the same job. GitLab silently ignores only:
when rules:
is also defined. The pipeline runs but the behavior isn't what you expect.
Check: Are you using rules:
OR only:
/except:
in each job? Pick one. (Use rules:
— only/except
is legacy.)
$CI_COMMIT_BRANCH
empty on MR pipelines A common bug: you ask for "this job runs on the default branch" and you get:
rules:
- if: $CI_COMMIT_BRANCH == "main"
This is correct for branch pipelines. It is empty on MR (merge_request_event
) pipelines. If you have MR pipelines enabled, your job silently won't run when developers expect it to.
Check: Does your pipeline target both push events and MR events? If so, you probably want $CI_MERGE_REQUEST_TARGET_BRANCH_NAME
or to handle both pipeline sources.
needs:
referencing hidden jobs
Hidden jobs (prefixed with .
) are templates — they don't execute. If you do needs: [".lint"]
, your job will fail with a confusing error because GitLab thinks you're depending on a job that doesn't exist.
Check: Every needs:
entry should be a real job name, not a template.
The model loves writing:
rules:
- if: $CI_COMMIT_BRANCH == "main"
when: always
- when: never
This works on main
but blocks the job on tags, on schedules, and on MR pipelines. Sometimes that's what you want. Often it's not.
Check: What pipeline sources do you expect this job to run in? List them, then verify your rules cover each.
This is the most expensive AI failure mode. The model will sometimes generate syntax for features that don't exist:
condition:
field that's actually OPA/Conftest, not GitLab CIauto_retry:
block that's GitHub Actions, not GitLabbefore_script:
keyword that does exist but with different semantics than the model claimsCheck: If you see a keyword you haven't seen before in GitLab docs, verify it exists. The lint endpoint (/api/v4/ci/lint
) catches most of these, but some pass lint and just behave weirdly.
I now do this for any non-trivial pipeline change:
curl -s --header "PRIVATE-TOKEN: $TOKEN" \
--header "Content-Type: application/json" \
--data "{\"content\": $(cat .gitlab-ci.yml | jq -Rs .)}" \
"$GITLAB_URL/api/v4/ci/lint" | jq
interruptible:
), revert them.Step 5 is the one most people skip. The model is good at writing YAML but not at preserving your previous decisions. If you don't diff, you'll lose your old cache strategy.
Last month I needed to add a job that runs terraform plan
on every MR and posts the output as a comment. Drafted with Claude in two minutes; it produced something like:
terraform-plan:
image: hashicorp/terraform:1.9
stage: plan
script:
- terraform init
- terraform plan -out=tfplan -no-color
- terraform show -no-color tfplan > plan.txt
- |
curl -X POST -H "PRIVATE-TOKEN: $GITLAB_API_TOKEN" \
-d "body=$(cat plan.txt | jq -Rs .)" \
"$CI_API_V4_URL/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/notes"
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
This is almost right. Two issues:
PRIVATE-TOKEN
as a CI variable$CI_JOB_TOKEN
for in-instance API calls. Saves rotation pain.terraform init -backend-config
Both fixes are 30 seconds. Without the AI I'd have spent 15 minutes writing the curl invocation alone.
AI doesn't replace knowing GitLab CI. It removes the typing and the boilerplate so you can spend your attention on the parts that matter — the rules:
logic, the cache keys, the secrets, the environment promotion.
Once you've internalized the failure modes above, the workflow becomes mostly automatic. You stop reading the boilerplate and start reading the rules. That's where the bugs live.
For the prompt set we use on GitLab CI specifically, see the GitLab CI/CD category — particularly gitlab-pipeline-optimization and gitlab-ci-rules-debugging.
This article was originally published on DevOps AI ToolKit — practical AI workflows for cloud engineers.