GitLab CI/CD 集成

Beta 阶段：此集成仍在测试中，由 GitLab 维护。

Claude Code 与 GitLab CI/CD 集成，让 AI 直接参与你的开发流程：在 Issue 或 MR 中 @claude，Claude 就会分析代码、创建分支、实现功能或修复 Bug。

能做什么

• 即时创建 MR：描述需求，Claude 生成完整变更并创建 MR
• 自动功能实现：把 Issue 变成可运行代码
• 遵循项目规范：自动读取 CLAUDE.md 中的代码风格指南
• 三种提供商：Claude API（SaaS）、AWS Bedrock、Google Vertex AI
• 安全：在你的 GitLab Runner 中运行，遵循分支保护和审批规则

工作原理

1. GitLab 监听触发条件（如 Issue/MR 评论中包含 @claude）
2. Pipeline 收集评论和仓库上下文，构建 Prompt
3. Claude Code 运行，在沙箱容器中安全执行
4. 所有变更通过 MR 提交，审查者可以看到完整 Diff

快速配置

第一步：添加 API Key

进入 Settings → CI/CD → Variables，添加 ANTHROPIC_API_KEY（设为 masked）。

第二步：添加 CI/CD 配置

在 .gitlab-ci.yml 中添加 Claude 任务：

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
  script:
    - /bin/gitlab-mcp-server || true
    - >
      claude
      -p "${AI_FLOW_INPUT:-'审查这个 MR 并实现请求的变更'}"
      --permission-mode acceptEdits
      --allowedTools "Bash Read Edit Write mcp__gitlab"
      --debug

配置完成后，可以在 CI/CD → Pipelines 手动测试，或在 MR 中触发。

使用示例

在 Issue 评论中：

@claude 根据 Issue 描述实现这个功能

在 MR 讨论中：

@claude 提出一个具体的方案来缓存这个 API 调用的结果

在 Issue 或 MR 评论中：

@claude 修复用户仪表板组件中的 TypeError

完整配置示例

基础版（Claude API 直连）

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
  script:
    - /bin/gitlab-mcp-server || true
    - >
      claude
      -p "${AI_FLOW_INPUT:-'总结最近的变更并提出改进建议'}"
      --permission-mode acceptEdits
      --allowedTools "Bash Read Edit Write mcp__gitlab"
      --debug

AWS Bedrock（OIDC 认证，无需静态密钥）

前提条件：

• 在 AWS IAM 中配置 GitLab OIDC
• 创建信任 GitLab OIDC 提供商的 IAM 角色，限制到你的项目
• 附加最小权限的 Bedrock 调用策略

需要的 CI/CD 变量：

• AWS_ROLE_TO_ASSUME：IAM 角色 ARN
• AWS_REGION：Bedrock 所在区域

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
    - curl -fsSL https://claude.ai/install.sh | bash
    # 用 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:-'实现请求的变更并创建 MR'}"
      --permission-mode acceptEdits
      --allowedTools "Bash Read Edit Write mcp__gitlab"
      --debug
  variables:
    AWS_REGION: "us-west-2"

Bedrock 的模型 ID 包含区域前缀，如 us.anthropic.claude-sonnet-4-6。

Google Vertex AI（Workload Identity Federation）

前提条件：

• GCP 项目中启用 Vertex AI API
• 配置 Workload Identity Federation 信任 GitLab OIDC
• 创建具有 Vertex AI 权限的服务账号

需要的 CI/CD 变量：

• GCP_WORKLOAD_IDENTITY_PROVIDER：完整 Provider 资源名
• GCP_SERVICE_ACCOUNT：服务账号邮箱
• CLOUD_ML_REGION：Vertex AI 区域（如 us-east5）

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 && apt-get clean
    - curl -fsSL https://claude.ai/install.sh | bash
    - >
      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:-'审查并按要求更新代码'}"
      --permission-mode acceptEdits
      --allowedTools "Bash Read Edit Write mcp__gitlab"
      --debug
  variables:
    CLOUD_ML_REGION: "us-east5"

最佳实践

通过 CLAUDE.md 指定项目规范

在仓库根目录创建 CLAUDE.md，定义编码标准、审查标准和项目特定规则。Claude 在运行时自动读取并遵循。

安全注意事项

• 绝不把 API Key 或云凭证提交到仓库，使用 GitLab CI/CD 变量
• 尽量使用 OIDC（无长期密钥）
• 限制 Job 权限和网络出口
• 像对待其他贡献者一样审查 Claude 的 MR

优化性能

• 保持 CLAUDE.md 简洁聚焦
• 提供清晰的 Issue/MR 描述，减少迭代次数
• 配置合理的 Job 超时时间
• 在 Runner 中缓存包安装

CI 费用

• GitLab Runner 时间：Claude 在你的 Runner 上运行，消耗计算分钟数
• API 费用：每次交互根据 Prompt 和响应大小消耗 Token

故障排查

Claude 不响应 @claude 命令：

• 确认 Pipeline 被正确触发
• 检查 CI/CD 变量是否存在且未被 mask 遮蔽
• 确认评论包含 @claude（不是 /claude）

Job 无法写评论或开 MR：

• 确认 CI_JOB_TOKEN 有足够权限，或使用具有 api scope 的 Project Access Token
• 检查 mcp__gitlab 工具已在 --allowedTools 中启用

认证失败：

• 检查 ANTHROPIC_API_KEY 是否有效
• Bedrock：确认 OIDC/WIF 配置正确，检查区域和模型可用性
• Vertex：确认服务账号有 Vertex AI 角色，WIF 配置正确

定制 Claude 行为

1. CLAUDE.md：定义编码标准、安全要求和项目规范
2. 自定义 Prompt：通过 AI_FLOW_INPUT 传入任务特定指令，不同 Job 可用不同 Prompt

相关资源

• GitHub Actions 集成：GitHub 版本的 CI/CD 集成
• CLI 参考：所有 claude_args 参数
• MCP 集成：扩展 Claude 可用工具
• 权限配置：工具权限控制