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
- GitLab notices a trigger. A manual run, a merge-request event, or a comment that mentions
@claudein an issue, an MR or a review thread — depending on the rules you wrote. - The job collects context. It reads the thread and the repository, builds a prompt from them, and runs Claude Code.
- Claude works inside a container. Each interaction runs with strict network and filesystem rules, and workspace-scoped permissions constrain what it can write.
- 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:
- Configure provider access. The Claude API stores
ANTHROPIC_API_KEYas 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. - Add project credentials for GitLab API operations. Use
CI_JOB_TOKENby default, or create a Project Access Token withapiscope and store it masked asGITLAB_ACCESS_TOKEN. - Add the Claude job to
.gitlab-ci.yml. - 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_INPUTandAI_FLOW_CONTEXTwhen 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
rulesare 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_scriptinstalls git, curl and bash, runs Anthropic's installer, and then fixesPATH— the installer putsclaudein~/.local/bin, which is not on the path in that image. GIT_STRATEGY: fetchis 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
echois there because web and API triggers pass their context asAI_FLOW_INPUT,AI_FLOW_CONTEXTandAI_FLOW_EVENT; without them the prompt falls back to "Review this MR and implement the requested changes". /bin/gitlab-mcp-server || truestarts a GitLab MCP server if your setup provides one, and the|| truekeeps the job alive when it does not.- The
claudecall runs headless with-p, accepts edits, and allows four Claude Code tools —Bash,Read,EditandWrite— plus the GitLab MCP toolmcp__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
@clauderather than/claude. - The job runs but cannot comment or open an MR. Give
CI_JOB_TOKENenough project permission, or switch to a Project Access Token withapiscope; confirmmcp__gitlabis in--allowedTools; and make sure the job has the MR context, throughAI_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
- Everything on this page: Claude Code GitLab CI/CD, read November 18, 2026.
- The same idea on GitHub's own pipeline: Claude Code GitHub Actions.
- The CLI the job calls, without a pipeline around it: Claude Code headless mode.
- Pricing for the model half of the bill: Anthropic pricing.
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.