Does Claude Code work with GitLab?
Yes. Claude Code works with GitLab through GitLab CI/CD. You add a Claude job to your .gitlab-ci.yml, store an API key as a masked CI/CD variable, and Claude runs inside a pipeline job: it reads the issue or merge request, makes changes in a branch, and opens or updates a merge request for you to review. Anthropic's docs label it beta and note that the integration is maintained by GitLab, not Anthropic.
This is different from using Claude Code on a project that happens to live on GitLab. If you clone a GitLab repo and open it in the Claude Code desktop app, Claude works on your files like any other project. The GitLab CI/CD integration is for the other case: you want Claude to work when you are not at your computer, triggered by the pipeline.
What Claude Code can do in a GitLab pipeline
- Create and update merge requests from an issue description or a comment.
- Implement a feature in a branch, then open a merge request.
- Fix bugs and regressions that tests or comments point to.
- Look into performance regressions and propose fixes.
- Respond to follow-up comments and keep iterating on the requested changes.
In practice that looks like a comment on an issue such as "@claude implement this feature based on the issue description", or on a merge request such as "@claude fix the TypeError in the user dashboard component". Claude reads the thread and the codebase, writes the change, and the result shows up as a merge request diff your team reviews like any other.
How to set up Claude Code in GitLab CI/CD
The quick setup from the docs takes two steps. I would write the job itself with Claude Code in the desktop app: open the repo, ask Claude to add a Claude job to .gitlab-ci.yml following the GitLab CI/CD guide, and review the diff before you push.
- Add a masked CI/CD variable. In your GitLab project go to Settings > CI/CD > Variables and add ANTHROPIC_API_KEY. Mark it masked, and protected if you only want it on protected branches.
- Add a Claude job to .gitlab-ci.yml. The example in the docs uses a Node Alpine image, installs git, curl and bash, installs Claude Code with the official install script, adds ~/.local/bin to the PATH, then runs claude -p with your instruction, --permission-mode acceptEdits and an --allowedTools list.
- Choose the trigger. The example job runs when you start the pipeline by hand from the web UI or on a merge request event. Start with the manual trigger only.
- Test it. Run the job from CI/CD > Pipelines, read the job log, and check the merge request Claude opens.
Making @claude mentions work
This is the part that trips people up. The quick setup job does not listen to comments by itself. Mention-driven triggers need an extra piece: a project webhook for Comments (notes) that sends events to an event listener you run, and that listener calls GitLab's pipeline trigger API with variables like AI_FLOW_INPUT and AI_FLOW_CONTEXT when a comment contains @claude.
- If Claude ignores a comment, first check that a pipeline actually started. If not, the webhook or listener is the problem, not Claude.
- The mention is @claude, not /claude.
- If the job runs but cannot comment or open a merge request, the token lacks permission. The docs say CI_JOB_TOKEN is the default, or use a Project Access Token with api scope stored as a masked GITLAB_ACCESS_TOKEN, and make sure the GitLab MCP tool is in --allowedTools.
Claude API, Amazon Bedrock or Google Cloud
Provider options for Claude Code in GitLab CI/CD, from Anthropic's docs
| Provider | How the job authenticates | Pick it when |
|---|---|---|
| Claude API | ANTHROPIC_API_KEY as a masked CI/CD variable | You want the fastest setup |
| Amazon Bedrock | GitLab OIDC exchanged for a short-lived IAM role, no static keys | Your company already buys Claude through AWS |
| Google Cloud | Workload Identity Federation impersonating a service account, no stored keys | Your company is on Google Cloud |
For a solo builder or a small team, the Claude API key is the simple choice. The cloud options matter when a company needs data residency, wants to use an existing cloud agreement, or does not allow long-lived keys in CI. The docs' manual setup is the one they recommend for production.
Keep the cost bounded before you automate it
Every run costs twice: GitLab runner minutes, and API tokens that depend on how big the task and the codebase are. A pipeline is also the place where a key can quietly spend while nobody is watching. So set the limits first, then turn on automatic triggers.
- Set --max-turns on the claude command so one job cannot go back and forth forever.
- Set GitLab's job-level timeout, for example timeout: 30m.
- Limit how many Claude jobs can run in parallel.
- Write specific @claude requests. Vague ones take more turns.
- Never commit the key. Keep it in a masked variable, and prefer OIDC on Bedrock or Google Cloud where you can.
- Keep CLAUDE.md short and focused. Claude reads it on every run.
The CI job uses an API key billed per token, not your Pro or Max plan. How much does Claude Code cost per month explains the difference.
GitLab pipeline or desktop app: which to use
Use the desktop app for the work you are doing right now. You see every step, steer it, and approve changes as they happen. Use the GitLab pipeline for work you want done while you are elsewhere, small fixes from issues, follow-up changes on a merge request, routine updates, where the merge request review is your checkpoint.
Both read the same CLAUDE.md, so put your conventions there once. The CLAUDE.md file guide covers what to include. The pipeline runs Claude in non-interactive mode with claude -p, the same mode explained in Claude Code headless mode.
Short, practical drops on skills, MCP, agents, prompts, and more. No spam, unsubscribe anytime.
Frequently asked questions
Does Claude Code work with GitLab?
Yes, through GitLab CI/CD. Add a Claude job to .gitlab-ci.yml and store your API key as a masked CI/CD variable. Claude then works on issues and merge requests inside your own runners. The integration is in beta and maintained by GitLab.
Is there a Claude Code GitLab app like the GitHub app?
No. On GitLab, setup is a pipeline job plus a masked variable. Comment-triggered runs need a webhook for comments and a listener that calls the pipeline trigger API when a comment contains @claude.
Why is Claude not responding to @claude in GitLab?
Usually the pipeline never started. Check that your comment webhook and listener are set up, that ANTHROPIC_API_KEY or your cloud variables exist, and that you wrote @claude, not /claude.
Can I use my Claude Pro or Max plan in GitLab CI?
The GitLab setup in Anthropic's docs authenticates with ANTHROPIC_API_KEY, Amazon Bedrock or Google Cloud, so runs are billed through that account, plus your GitLab runner minutes.
How do I stop Claude Code from running up costs in GitLab?
Set --max-turns on the claude command, a job timeout in .gitlab-ci.yml, limit parallel runs, start with manual triggers, and set a spend limit on the API key.
Last reviewed by David Iya on October 21, 2026
