结论先说
- Claude Code 在 GitLab 流水线里底层靠无头模式(
claude -p)驱动:无需任何特殊商业网关,只要 Runner 容器能访问 Anthropic 接口(或企业 Bedrock / Vertex 网关)就能跑。 - 密钥必须配置在 GitLab 的 CI/CD Variables 并勾选掩码(Masked):注意不要盲目勾选「仅受保护分支(Protected)」,否则普通功能分支提上来的 Merge Request 拿不到变量会直接报未授权。
- 容器里最常踩的坑是漏加
PATH:官方原生安装脚本把可执行文件放在~/.local/bin,在轻量容器before_script里必须显式把它导出进PATH。 - 安全第一原则:自动审 MR 的作业只开放只读工具与评论接口,去掉
Edit和Write,防止提示词注入篡改流水线源码。

图:本站根据 Claude Code 官方文档 GitLab CI/CD 整理的示意图
本文根据 Claude Code 官方文档《Claude Code GitLab CI/CD》与《Run Claude Code programmatically》整理,核对日期 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 Anthropic 或 GitLab 官方网站。
适用于谁
- 搜「claude code gitlab ci」「gitlab merge request 自动代码审查 claude」的研发与运维工程师;
- 公司代码托管在 GitLab(含极狐或内网自建实例),没法直接套用 GitHub Actions 现成插件(见 /guides/claude-code-github-actions),需要手写
.gitlab-ci.yml跑自动化审查或修补的人; - 在容器流水线里装完 Claude Code 后一直报
claude: not found或 401 读不到密钥的人。
一、第一步:在 GitLab 项目后台配好安全凭证
CI 容器没有人工交互界面,不能走个人网页订阅登录,必须走开发者密钥或云平台凭证(认证差异见 /guides/claude-code-use-api-key-instead-of-login):
- 打开目标 GitLab 仓库,依次进入 设置(Settings) → CI/CD → 变量(Variables);
- 新增变量
ANTHROPIC_API_KEY,填入在控制台创建的专用流水线密钥,勾选 掩码变量(Mask variable) 防止密钥打印进构建日志; - 如果需要让作业把审查意见自动回写到当前 Merge Request 评论区,再创建一个最小范围(
api或只读加讨论权限)的项目访问令牌(Project Access Token),存为GITLAB_TOKEN。
二、第二步:编写 .gitlab-ci.yml 只读审查模板
下面是一个在每次提交或更新 Merge Request 时自动对比目标分支改动、调用 glab(或内部接口)发表审查摘要的标准作业模板(无头参数细节见 /guides/claude-code-headless-mode):
yaml
stages:
- ai-review
claude_mr_review:
stage: ai-review
image: node:22-bookworm-slim
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
variables:
GIT_DEPTH: 0
before_script:
- apt-get update && apt-get install -y --no-install-recommends git curl ca-certificates
- curl -fsSL https://claude.ai/install.sh | bash
- export PATH="$HOME/.local/bin:$PATH"
script:
- git fetch origin "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
- >
claude -p "对比 origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME...HEAD 的代码变更,
只指出会导致线上故障、越权漏洞或缺失边界处理的实质缺陷,跳过纯代码风格建议,输出简洁 Markdown。"
--allowedTools "Read,Grep,Glob,Bash(git diff *),Bash(git log *)"
--max-turns 8 > review_report.md
- cat review_report.md
artifacts:
paths:
- review_report.md
expire_in: 7 days
看清模板里的三处关键防护设计:
GIT_DEPTH: 0确保容器拉取完整分支引用,避免git diff找不到目标基准分支提交;--allowedTools严格把Bash收窄到只允许执行git diff和git log,不给任意命令执行权,也没有放行Edit与Write;--max-turns 8封死单次作业最大工具循环轮数,避免遇到超大变更集把整个月 API 预算跑穿。拿到review_report.md后,只需加一行调用 GitLab Notes API 或glab mr note即可把报告贴回 MR 页面(团队审查分工规范见 /guides/claude-code-team-code-review-workflow)。

图:本站根据 Claude Code 官方文档 GitLab CI/CD 整理的示意图
三、需要让流水线「自动改代码提交」时怎么放权
除了只读审查,官方 GitLab 文档也支持「手动在网页触发流水线并传入修改指令(如修单测、补类型注解)」的写入模式。若要启用自动改码,请务必把写入作业和自动触发的公开 MR 作业分开:
- 将触发条件限制为
$CI_PIPELINE_SOURCE == "web"(仅限仓库内部有权限的研发人员手动点运行并传入需求变量),不要对外部未知派生仓库自动开放写权限; - 在该受控作业里加上
--permission-mode acceptEdits并放行Edit、Write与受限测试命令,改完跑绿单测后再由脚本创建独立修补分支供人工合并。
平时成员在本地终端先用自己的 Claude Code 预审改完再推 GitLab,能大幅减少 CI 流水线反复重跑的开销;个人本地研发环境的官方订阅方案可参考 /chongzhi/claude-code。
常见问题
Q:每次起流水线都重新 curl 下载安装一遍太慢怎么办?
生产团队强烈建议基于内部基础镜像预先把 Claude Code、git 和 glab 打进自定义 Runner 镜像推到内网镜像仓库(Harbor / GitLab Container Registry),流水线启动直接秒进 script 阶段,还能彻底避免外网下载波动导致构建偶发失败。
Q:企业合规要求走 AWS Bedrock 或 Google Vertex AI 怎么改配置?
按官方文档,在 GitLab CI/CD Variables 里配置 CLAUDE_CODE_USE_BEDROCK=1(或 CLAUDE_CODE_USE_VERTEX=1)并配合 GitLab OIDC 身份联合换取临时云凭证即可,连长期静态 ANTHROPIC_API_KEY 都不用存。
Q:怎么让流水线审查遵守我们团队自己的业务规范?
不需要把几千字规范全塞进 .gitlab-ci.yml 的 -p 命令字符串里。只要你的仓库根目录已经提交了团队共享的 CLAUDE.md 和 .claude/rules/ 规则文件,无头运行的 claude -p 启动时会自动读取仓库上下文,按同一把尺子检查每次提交。
相关教程
- /guides/claude-code-github-actions:Claude Code 在 GitHub Actions 中的配置对比
- /guides/claude-code-headless-mode:
claude -p非交互模式参数与脚本自动化详解 - /guides/claude-code-team-code-review-workflow:团队双层代码审查工作流设计
- /guides/claude-code-use-api-key-instead-of-login:Claude Code 配置 API Key 与云平台认证
参考资料
- Claude Code 官方文档:Claude Code GitLab CI/CD — https://code.claude.com/docs/en/gitlab-ci-cd
- Claude Code 官方文档:Run Claude Code programmatically — https://code.claude.com/docs/en/headless
0 条评论
还没有评论,来抢沙发~