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.

What AI gets right consistently

Standard job shapes

"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:

• Test jobs across languages (pytest, jest, go test, etc.)
• Standard cache configurations
• Standard artifact patterns
• Basic rules: for branch / tag / MR pipelines

If you find yourself writing one of these from scratch, you're spending time that you don't need to spend.

Translating from other CIs

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.

Reviewing pipelines for inefficiency

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:

• "Your test job downloads node_modules from cache, but install-deps doesn't push to cache — your cache key is broken."
• "Your build and deploy stages are sequential but build's artifacts aren't used by deploy — they can be parallel with needs:."
• "Your 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.

What AI gets wrong — and how to catch it

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.

Auto-apply rules that don't include the right branches

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.

Imaginary GitLab features

This is the most expensive AI failure mode. The model will sometimes generate syntax for features that don't exist:

• A condition: field that's actually OPA/Conftest, not GitLab CI
• An auto_retry: block that's GitHub Actions, not GitLab
• A 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.

A workflow that catches the failures cheaply

I now do this for any non-trivial pipeline change:

1. Draft with AI. Describe the desired behavior in plain English; let the model write the YAML.
2. Read every line. Treat the output as a draft you'd write yourself.
3. Lint via the API.

   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

1. Run on a sandbox branch. Push to a branch that won't trigger deploys; verify the pipeline runs the jobs you expect, when you expect.
2. Diff against the existing pipeline. If the AI introduced changes you didn't ask for (a different cache key, a removed 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.

A practical example

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:

1. PRIVATE-TOKEN as a CI variable — using a personal access token for CI is the old pattern. Modern approach: use $CI_JOB_TOKEN for in-instance API calls. Saves rotation pain.
2. No terraform init -backend-config — works if the backend is configured in code, but if you have multiple environments using the same module, you'd want to specify which backend.

Both fixes are 30 seconds. Without the AI I'd have spent 15 minutes writing the curl invocation alone.

The bottom line

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.