GitLab CI/CD

GitLab CI/CD

GitLab CI/CD 和 GitHub Actions 是双胞胎兄弟——同样的「事件触发 job」模型，同样的容器化运行。如果你在 GitLab 上做工程，Claude Code 同样能进你的工作流：在 issue、MR 评论里 @claude mention，让 Claude 接管任务，把改动以 MR 形式推回来。

这一页讲清楚 GitLab CI 怎么接 Claude，三种 provider（Claude API、AWS Bedrock、Google Vertex AI）怎么选，以及生产环境的关键配置。

注：Claude Code for GitLab CI/CD 目前是 beta。集成由 GitLab 维护，功能可能持续演化；遇到问题可在 GitLab 官方 issue 反馈。

为什么用 GitLab CI 接 Claude

优点	说明
Instant MR creation	描述需求，Claude 提交完整 MR（带改动与说明）
Automated implementation	一句话把 issue 变成工作代码
Project-aware	Claude 读 CLAUDE.md，遵循你的代码模式
Simple setup	一个 job + 一个 masked variable 即可起步
Enterprise-ready	三种 provider 任选，满足数据驻留与采购要求
Secure by default	跑在你的 GitLab runner 里，受分支保护和审批规则约束

集成构建在 Claude Code CLI 和 SDK 之上，支持编程化使用 Claude 完成自定义自动化。

工作原理

1. 事件驱动编排：GitLab 监听你设的触发器（例如评论里 @claude mention），job 收集 thread 与仓库上下文，组装 prompt，跑 Claude Code。
2. Provider 抽象：三种 provider 任选——Claude API（SaaS）、AWS Bedrock（IAM 鉴权、跨区域）、Google Vertex AI（GCP 原生、Workload Identity Federation）。
3. 沙盒化执行：每次交互跑在容器里，严格的网络与文件系统规则。Claude Code 强制 workspace 范围权限约束写入。每个改动走 MR，评审人能看到 diff、审批依然有效。

Quick setup

最快上手：往 .gitlab-ci.yml 加一个 job，再加一个 masked API key 变量。

1. 加 masked CI/CD variable

进 Settings → CI/CD → Variables，加 ANTHROPIC_API_KEY（勾 masked，需要时勾 protected）。

2. 加 Claude job

stages:
  - ai
claude:
  stage: ai
  image: node:24-alpine3.21
  # 调整触发条件：手动 / MR 事件 / 评论里包含 @claude 时
  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
    - npm install -g @anthropic-ai/claude-code
  script:
    # 可选：启动 GitLab MCP server
    - /bin/gitlab-mcp-server || true
    # 通过 web/API trigger 时用 AI_FLOW_* 变量带上下文
    - 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

加完后从 CI/CD → Pipelines 手动跑一次测试，或在 MR 上触发让 Claude 在分支里改代码并开 MR。mcp__gitlab 工具能让 Claude 直接调 GitLab API 写评论、开 MR。

Manual setup（生产推荐）

需要更受控的配置或用 Bedrock/Vertex：

1. 配 provider 访问：
   • Claude API：ANTHROPIC_API_KEY 作 masked variable
   • AWS Bedrock：配 GitLab → AWS OIDC，建一个有 Bedrock 权限的 IAM role
   • Google Vertex AI：配 Workload Identity Federation
2. 加项目凭证：默认用 CI_JOB_TOKEN；要更强权限则建 Project Access Token（api scope），存成 GITLAB_ACCESS_TOKEN
3. 加 Claude job 到 .gitlab-ci.yml（见上面 quick setup）
4. （可选）开 mention 触发：用 webhook 监听「Comments (notes)」事件，让 listener 调 pipeline trigger API，传 AI_FLOW_INPUT 和 AI_FLOW_CONTEXT 变量

常见用例

issue 评论里

@claude implement this feature based on the issue description

Claude 分析 issue 和代码库，在分支里写改动并开 MR 评审。

MR 讨论里

@claude suggest a concrete approach to cache the results of this API call

Claude 提出方案，加上合适的缓存代码，更新 MR。

修 Bug

@claude fix the TypeError in the user dashboard component

Claude 定位 bug，实现修复，更新分支或开新 MR。

AWS Bedrock job 示例（OIDC）

claude-bedrock:
  stage: ai
  image: node:24-alpine3.21
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web"'
  before_script:
    - apk add --no-cache bash curl jq git python3 py3-pip
    - pip install --no-cache-dir awscli
    - npm install -g @anthropic-ai/claude-code
    # 用 GitLab OIDC token 换 AWS 凭证
    - export AWS_WEB_IDENTITY_TOKEN_FILE="${CI_JOB_JWT_FILE:-/tmp/oidc_token}"
    - if [ -n "${CI_JOB_JWT_V2}" ]; then printf "%s" "$CI_JOB_JWT_V2" > "$AWS_WEB_IDENTITY_TOKEN_FILE"; fi
    - >
      aws sts assume-role-with-web-identity
      --role-arn "$AWS_ROLE_TO_ASSUME"
      --role-session-name "gitlab-claude-$(date +%s)"
      --web-identity-token "file://$AWS_WEB_IDENTITY_TOKEN_FILE"
      --duration-seconds 3600 > /tmp/aws_creds.json
    - export AWS_ACCESS_KEY_ID="$(jq -r .Credentials.AccessKeyId /tmp/aws_creds.json)"
    - export AWS_SECRET_ACCESS_KEY="$(jq -r .Credentials.SecretAccessKey /tmp/aws_creds.json)"
    - export AWS_SESSION_TOKEN="$(jq -r .Credentials.SessionToken /tmp/aws_creds.json)"
  script:
    - /bin/gitlab-mcp-server || true
    - >
      claude
      -p "${AI_FLOW_INPUT:-'Implement the requested changes and open an MR'}"
      --permission-mode acceptEdits
      --allowedTools "Bash(*) Read(*) Edit(*) Write(*) mcp__gitlab"
      --debug
  variables:
    AWS_REGION: "us-west-2"

需要的 CI/CD 变量：AWS_ROLE_TO_ASSUME、AWS_REGION。Bedrock 模型 ID 带区域前缀和版本后缀（如 us.anthropic.claude-sonnet-4-5-20250929-v1:0）。

Google Vertex AI job 示例（WIF）

claude-vertex:
  stage: ai
  image: gcr.io/google.com/cloudsdktool/google-cloud-cli:slim
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web"'
  before_script:
    - apt-get update && apt-get install -y git nodejs npm && apt-get clean
    - npm install -g @anthropic-ai/claude-code
    - >
      gcloud auth login --cred-file=<(cat <<EOF
      {
        "type": "external_account",
        "audience": "${GCP_WORKLOAD_IDENTITY_PROVIDER}",
        "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
        "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/${GCP_SERVICE_ACCOUNT}:generateAccessToken",
        "token_url": "https://sts.googleapis.com/v1/token"
      }
      EOF
      )
  script:
    - /bin/gitlab-mcp-server || true
    - >
      CLOUD_ML_REGION="${CLOUD_ML_REGION:-us-east5}"
      claude
      -p "${AI_FLOW_INPUT:-'Review and update code as requested'}"
      --permission-mode acceptEdits
      --allowedTools "Bash(*) Read(*) Edit(*) Write(*) mcp__gitlab"
      --debug
  variables:
    CLOUD_ML_REGION: "us-east5"

需要的 CI/CD 变量：GCP_WORKLOAD_IDENTITY_PROVIDER、GCP_SERVICE_ACCOUNT、CLOUD_ML_REGION。WIF 免去下载 service account key，更安全。

最佳实践

CLAUDE.md 配置

仓库根目录放一份 CLAUDE.md，定义编码规范、审查标准、项目规则。Claude 跑任务时会读它，遵循你的约定。

安全

• 永不 commit API key 或云凭证
• 用 GitLab CI/CD variables（masked + protected）
• 尽量用 provider 特定的 OIDC，避免长生命周期的静态 key
• 限制 job 权限和网络出口
• 把 Claude 的 MR 当普通贡献者评审

性能

• CLAUDE.md 保持精炼聚焦
• issue/MR 描述写清楚，减少迭代次数
• 配合理的 job timeout，防失控
• runner 里缓存 npm 和包安装

CI 成本

成本类型	说明
GitLab Runner 时间	跑在你的 runner 上，消耗 compute 分钟数
API 成本	每次交互消耗 token，量取决于任务复杂度和代码库大小

省钱技巧：用具体的 @claude 命令避免不必要轮次；设合适的 max_turns 和 timeout；用 concurrency 控制并行。

Troubleshooting

症状	排查
@claude 没反应	pipeline 是否被触发（手动/MR 事件/notes listener webhook）；ANTHROPIC_API_KEY 或 cloud provider 变量是否在且 unmasked；评论里写的是 @claude 不是 /claude
job 不能写评论或开 MR	CI_JOB_TOKEN 权限够吗；或用 Project Access Token（api scope）；mcp__gitlab 是否在 --allowedTools 里
认证错误	Claude API：检查 ANTHROPIC_API_KEY；Bedrock/Vertex：验证 OIDC/WIF 配置、role 名、secret 名、区域和模型可用性

安全与治理

• 每个 job 跑在隔离容器里，网络受限
• Claude 的改动走 MR，评审人能看到每个 diff
• 分支保护和审批规则对 AI 生成的代码同样适用
• workspace 范围权限约束写入
• 自带 provider 凭证，成本你自己掌控

一句话总结

GitLab CI 接 Claude 和 GitHub Actions 同源同思：一个 .gitlab-ci.yml job + 一个 masked variable 起步，mcp__gitlab 工具让 Claude 真正能写评论开 MR，Bedrock/Vertex 让企业把数据留在自己云里。

下一篇看 后台会话，把任务甩到后台让 Claude 自己慢慢跑。🧵