Claude Code 接入 GitLab CI/CD 教程:.gitlab-ci.yml 配置与自动审查 Merge Request

很多企业内网或自托管仓库用的是 GitLab 而不是 GitHub。本文根据 Claude Code 官方 GitLab CI/CD 文档,讲清 CI 变量掩码配置、.gitlab-ci.yml 作业模板、PATH 路径避坑以及只读审查 Merge Request 的最小权限写法。

NNathaniel bigo··原创首发·AI 辅助撰写
9 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 其他 账号

结论先说

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

Claude Code 接入 GitLab CI 四步

图:本站根据 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):

  1. 打开目标 GitLab 仓库,依次进入 设置(Settings) → CI/CD → 变量(Variables);
  2. 新增变量 ANTHROPIC_API_KEY,填入在控制台创建的专用流水线密钥,勾选 掩码变量(Mask variable) 防止密钥打印进构建日志;
  3. 如果需要让作业把审查意见自动回写到当前 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)。

GitLab 流水线常见报错与权限排查

图:本站根据 Claude Code 官方文档 GitLab CI/CD 整理的示意图

三、需要让流水线「自动改代码提交」时怎么放权

除了只读审查,官方 GitLab 文档也支持「手动在网页触发流水线并传入修改指令(如修单测、补类型注解)」的写入模式。若要启用自动改码,请务必把写入作业和自动触发的公开 MR 作业分开:

  1. 将触发条件限制为 $CI_PIPELINE_SOURCE == "web"(仅限仓库内部有权限的研发人员手动点运行并传入需求变量),不要对外部未知派生仓库自动开放写权限;
  2. 在该受控作业里加上 --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 启动时会自动读取仓库上下文,按同一把尺子检查每次提交。

相关教程

参考资料

  • 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

Nathaniel 的更多内容

  1. 01

    LangGraph 流式输出(Streaming)详解:逐字 Token 流、节点进度与自定义事件写法

    多步智能体如果等全部节点跑完才返回,网页前端就会白屏干等十几秒。本文按 LangGraph 官方文档讲清 updates、messages、custom 与 values 四种 stream_mode 的区别,以及组合订阅逐字打字机输出加工具内部实时进度的完整代码。

    其他 AI 工具0
  2. 02

    LangGraph 持久化与长期记忆怎么配:Checkpointer、Store 与 PostgreSQL 实战

    在生产环境跑 LangGraph,单靠 InMemorySaver 一重启就会丢失全部对话。本文按官方文档讲清线程内短期检查点(Checkpointer)与跨线程长期记忆(Store)的分工,以及用 langgraph-checkpoint-postgres 对接 PostgreSQL 的完整步骤。

    其他 AI 工具0
  3. 03

    LangGraph 多智能体怎么写:Supervisor 主管包与 Subgraph 隔离子图实战

    在 LangGraph 里把单个图扩展成多智能体协作有两条官方路线:快速原型用预置包 langgraph-supervisor,大型生产系统用原生子图(Subgraph)嵌套。本文讲清两种写法的完整代码、私有状态隔离防 Token 膨胀技巧以及检查点传播规则。

    其他 AI 工具0
  4. 04

    LangGraph 人工介入审批怎么写:interrupt 暂停图运行与 Command 恢复实战

    企业之所以选 LangGraph,很大程度看中它能安全挂起等待人工审批(Human-in-the-Loop)。本文按官方最新规范讲清 interrupt() 动态暂停、Checkpointer 必备条件、Command(resume=...) 恢复执行,以及防止副作用重复运行的重入规则。

    其他 AI 工具0
  5. 05

    多 Agent 协作平台怎么选:Dify、扣子(Coze)、n8n 与 LangGraph 多智能体机制对比

    搜「多agent协作平台」时,Dify、扣子、n8n 和 LangGraph 都宣称支持多智能体,但底层的调度方式完全不同。本文跳过基础安装,专门从多 Agent 角色跳转、子代理工具调用、上下文隔离与私有化部署四个维度帮你一次选准。

    其他 AI 工具0
  6. 06

    企业微信有官方 MCP 和 CLI 吗:@wecom/cli 安装初始化、长连接机器人与接入教程

    搜「企业 微信 有 mcp 吗」不用再东拼西凑民间群机器人脚本了:企业微信官方已推出 @wecom/cli 命令行工具并内置 stdio 模式的 MCP Server。本文按官方开发者文档讲清安装、智能机器人长连接初始化、业务命令与接入 Claude Code 步骤。

    Claude其他 AI 工具0

同产品的其他教程

  1. 01

    MCP 收费吗:开源协议免费边界、第三方 API 账单与隐形 Token 开销说明

    搜「mcp 收费 吗」的人常担心装多了插件会被扣费。MCP(模型上下文协议)本身和官方 SDK 采用 MIT 协议完全免费;实际使用中可能产生费用的只有两处:挂载过多工具占用的大模型上下文 Token,以及部分外部商业数据源自带的 API 套餐。

    Claude其他 AI 工具0
  2. 02

    MCP 协议最新版本更新了什么:无状态架构、OAuth 2.1、结构化输出与异步 Tasks 详解

    搜「mcp 重大 更新」「mcp 协议 更新」想补齐规范演进脉络?本文对照 modelcontextprotocol.io 官方规范更新日志,梳理从 Streamable HTTP 到无状态优先架构、OAuth 2.1 资源服务器、Elicitation 交互补参与异步 Tasks 扩展的核心变化。

    Claude其他 AI 工具0
  3. 03

    A2A 和 MCP 有什么区别:工具连接协议与智能体通信协议的边界和配合

    很多人问「有了 MCP 为什么还要出 A2A,两者是不是二选一的竞争关系」。两份官方规范都明确写明它们是上下互补关系:MCP 负责给单个智能体挂载工具与数据源,A2A 负责让多个独立黑盒智能体跨团队、跨框架互相派单协作。

    Claude其他 AI 工具0
  4. 04

    LangGraph 怎么使用 MCP:用 langchain-mcp-adapters 接入本地与远程工具

    想让自建的 LangGraph 状态图直接调用现成的 MCP 服务器,官方标准方案是安装 langchain-mcp-adapters 并使用 MultiServerMCPClient。本文讲清 stdio 与 streamable_http 两种配置写法、异步图运行及按节点分工具技巧。

    Claude其他 AI 工具0
  5. 05

    LangGraph 入门教程:Python 安装、核心概念与跑通第一个状态图智能体

    面向搜「python 安装 langgraph」和「langgraph 中文 文档」的初学者:本文按 LangChain 官方最新 Graph API 规范,讲清安装步骤、State/Node/Edge 四大概念,并从零写出第一个带工具调用循环的 StateGraph。

    Claude其他 AI 工具0
  6. 06

    Claude Agent SDK 子代理怎么写:AgentDefinition 配置、权限收敛与 Python/TS 示例

    在 Python 或 TypeScript 里用 Claude Agent SDK 编排多角色协作,核心是配置 ClaudeAgentOptions 的 agents 字段与 AgentDefinition。本文讲清必开的 Agent 委派权限、工具收敛、模型分级与完整代码示例。

    Claude0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~