AI for GitLab CI Authoring: Save Hours, Avoid Footguns

A developer reports that AI assistants like Claude can save hours authoring GitLab CI YAML pipelines, but warns of common pitfalls including rules/except confusion, empty variables on MR pipelines, and hidden job references. The engineer recommends using AI for translating between CI systems and for pipeline optimization reviews, while always verifying unfamiliar keywords against GitLab docs.

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: php 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: php 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 CI auto retry: block that's GitHub Actions, not GitLab before script: keyword that does exist but with different semantics than the model claims Check: 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 https://dev.to/categories/gitlab-cicd/ — particularly gitlab-pipeline-optimization https://dev.to/prompts/gitlab-pipeline-optimization/ and gitlab-ci-rules-debugging https://dev.to/prompts/gitlab-ci-rules-debugging/ . This article was originally published on DevOps AI ToolKit — practical AI workflows for cloud engineers.