Omniscio

OmniscioGuidesClaude Code in GitLab CI/CD

Claude Code in GitLab CI/CD: @claude in a merge request

GitLab's integration is the CI-shaped version of Claude Code: no terminal, no local install to keep current, just a job that runs on your own runners and answers in the merge request where the work is being discussed.

This page covers the one variable and one job that turn it on, what each line of that job is doing, the providers it can run against, and the three reasons a run goes quiet.

Last checked against Anthropic's Claude Code documentation on November 18, 2026. By the Omniscio team. Updated .

What it is

Claude Code for GitLab CI/CD runs Claude inside your own GitLab jobs. It is built on the Claude Code CLI and the Agent SDK, which is what lets a pipeline call it with ordinary flags such as -p, and it is in beta, maintained by GitLab rather than by Anthropic.

What that buys you is short to list: an issue description turned into a merge request, a comment that becomes working code, and analysis of a performance regression — all as a reviewable diff, with Claude following the CLAUDE.md rules already in the repository.

The part people underestimate is where it runs. It is your GitLab runner, under your branch protection, using your provider account — the code is cloned and changed on runners you control.

Sources: the beta note and "Why use Claude Code with GitLab?" in Anthropic's GitLab CI/CD page, read November 18, 2026.

How a run works

  1. GitLab notices a trigger. A manual run, a merge-request event, or a comment that mentions @claude in an issue, an MR or a review thread — depending on the rules you wrote.
  2. The job collects context. It reads the thread and the repository, builds a prompt from them, and runs Claude Code.
  3. Claude works inside a container. Each interaction runs with strict network and filesystem rules, and workspace-scoped permissions constrain what it can write.
  4. The result arrives as a merge request. Every change flows through an MR, so reviewers see the diff and approvals still apply.

Source: "How it works" in Anthropic's GitLab CI/CD page, read November 18, 2026.

The setup, in full

Quick setup is two steps: in Settings → CI/CD → Variables, add ANTHROPIC_API_KEY as a masked variable; then add a Claude job to .gitlab-ci.yml. The next section walks the job.

Anthropic recommends the manual setup for production, because it adds the two things a real project needs — provider credentials chosen deliberately, and a token that can write comments and open MRs:

  1. Configure provider access. The Claude API stores ANTHROPIC_API_KEY as a masked variable. Amazon Bedrock needs GitLab configured as an AWS OIDC identity provider plus an IAM role. Google Cloud's Agent Platform needs Workload Identity Federation for GitLab to GCP.
  2. Add project credentials for GitLab API operations. Use CI_JOB_TOKEN by default, or create a Project Access Token with api scope and store it masked as GITLAB_ACCESS_TOKEN.
  3. Add the Claude job to .gitlab-ci.yml.
  4. Optionally, enable mention-driven triggers. Add a project webhook for comments and have your listener call the pipeline trigger API with variables such as AI_FLOW_INPUT and AI_FLOW_CONTEXT when a comment contains @claude.

That last step is the one that surprises people: @claude is not magic on its own. The word "listener" hides a component you have to supply — a small service that receives GitLab's comment webhook and calls the pipeline trigger API with the comment's text and context. A mention with no such listener behind it sits there forever, which is why silence is the first symptom in the troubleshooting section.

Source: "Quick setup" and "Manual setup (recommended for production)" in Anthropic's GitLab CI/CD page, read November 18, 2026.

The job file, line by line

The quick-setup job, as Anthropic publishes it:

stages:
  - ai

claude:
  stage: ai
  image: node:24-alpine3.21
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web"'
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  variables:
    GIT_STRATEGY: fetch
  before_script:
    - apk update
    - apk add --no-cache git curl bash
    - curl -fsSL https://claude.ai/install.sh | bash
    - export PATH="$HOME/.local/bin:$PATH"
  script:
    - /bin/gitlab-mcp-server || true
    - echo "$AI_FLOW_INPUT for $AI_FLOW_CONTEXT on $AI_FLOW_EVENT"
    - >
      claude
      -p "${AI_FLOW_INPUT:-'Review this MR and implement the requested changes'}"
      --permission-mode acceptEdits
      --allowedTools "Bash Read Edit Write mcp__gitlab"
      --debug
  • The two rules are the triggers: a pipeline started from the web UI, or a merge-request event. Add your own for note events or API triggers.
  • The before_script installs git, curl and bash, runs Anthropic's installer, and then fixes PATH — the installer puts claude in ~/.local/bin, which is not on the path in that image.
  • GIT_STRATEGY: fetch is a GitLab keyword rather than a Claude Code one: it re-uses the runner's local working copy and fetches the commits made since the last job, instead of cloning from scratch.
  • The echo is there because web and API triggers pass their context as AI_FLOW_INPUT, AI_FLOW_CONTEXT and AI_FLOW_EVENT; without them the prompt falls back to "Review this MR and implement the requested changes".
  • /bin/gitlab-mcp-server || true starts a GitLab MCP server if your setup provides one, and the || true keeps the job alive when it does not.
  • The claude call runs headless with -p, accepts edits, and allows four Claude Code tools — Bash, Read, Edit and Write — plus the GitLab MCP tool mcp__gitlab.

Test it by running the job manually from CI/CD → Pipelines, or by triggering it from an MR. --max-turns and a GitLab job-level timeout are the two dials for bounding a run.

Source: the quick-setup job and "Common parameters and variables" in Anthropic's GitLab CI/CD page, read November 18, 2026.

Three providers

The provider is chosen in the job, not in a setting, and the choice is mostly about procurement and data residency:

  • Claude API — one masked ANTHROPIC_API_KEY, the shortest road.
  • Amazon Bedrock — IAM-based access with cross-region options, through a GitLab OIDC identity provider and a role trust policy restricted to your project and refs.
  • Google Cloud's Agent Platform — GCP-native, through Workload Identity Federation for GitLab.

The benefit of the last two is that they use infrastructure you already have contracts for, and regional endpoints can cut latency and satisfy data-sovereignty rules. The cost is more setup before the first run.

Sources: "How it works", "Using with Amazon Bedrock and Google Cloud" and "Configuration examples" in Anthropic's GitLab CI/CD page, read November 18, 2026.

Security, and what a run costs

Two rules cover the security side: never commit keys or cloud credentials to the repository — always masked CI/CD variables — and use provider OIDC where you can, so no long-lived key exists. Anthropic also advises limiting job permissions and network egress, and reviewing Claude's MRs like any other contributor's.

A run has two bills. The GitLab runner consumes compute minutes on your plan. The model is billed per token to whichever provider the job names, and token use scales with task complexity and codebase size.

The three levers Anthropic names for keeping that down: specific @claude instructions to cut unnecessary turns, sensible --max-turns and job timeout values, and limited concurrency so parallel runs do not multiply the bill.

Sources: "Security considerations" and "CI costs" in Anthropic's GitLab CI/CD page, read November 18, 2026.

When @claude says nothing

Three failures, in the order they happen.

  • No response to an @claude command. Check that a pipeline was actually triggered — manually, by an MR event, or by a note event through your listener — that the API key or provider variables are present, and that the comment says @claude rather than /claude.
  • The job runs but cannot comment or open an MR. Give CI_JOB_TOKEN enough project permission, or switch to a Project Access Token with api scope; confirm mcp__gitlab is in --allowedTools; and make sure the job has the MR context, through AI_FLOW_* variables if it was triggered from the web or API.
  • An authentication error. On the Claude API, the key is invalid or expired. On Bedrock or Google Cloud, it is OIDC or Workload Identity Federation, role impersonation, a secret name, or a region and model that is not available.

Source: "Troubleshooting" in Anthropic's GitLab CI/CD page, read November 18, 2026.

Where these answers come from

Common questions

Does Claude commit straight to my branch?

No. Changes flow through a merge request, so branch protection and approvals still apply and reviewers see the diff.

Which account pays for a GitLab run?

Yours: tokens go to the provider the job names, and the job also consumes GitLab runner minutes on your plan.

Why does @claude get no response?

Usually nothing triggered the pipeline, the key or provider variables are missing, or the comment used /claude instead of @claude.

Can the job comment on issues and open MRs?

Yes, if its token can: CI_JOB_TOKEN with enough project permission, or a Project Access Token with api scope, plus mcp__gitlab in --allowedTools.