古法编程

Claude Code GitLab CI/CD 配置：@claude 自动创建 MR 与 AI 代码实现

在 GitLab CI/CD 里使用 Claude Code，你可以在 Issue 或 MR 中 @claude，Claude 分析代码、创建分支、实现功能或修复 Bug，所有变更通过 MR 提交，分支保护和审批规则照常生效。支持 Claude API 直连、AWS Bedrock（IAM OIDC）或 Google Vertex AI（Workload Identity Federation）三种认证，无需长期密钥。添加一个 CI/CD Job 和 API Key 变量即可快速接入。

当前集成处于 Beta 阶段，功能可能逐步优化。该集成由 GitLab 维护，如需支持请参阅 GitLab issue。

此集成基于 Claude Code CLI 和 Agent SDK，可在 CI/CD Job 和自定义自动化流程中以编程方式调用 Claude。

为什么在 GitLab 中使用 Claude Code

  • 即时 MR 创建：描述需求，Claude 提出包含变更和说明的完整 MR
  • 自动实现：单个命令或 @claude 将 Issue 转化为可工作代码
  • 项目感知：Claude 读取 CLAUDE.md 指南并遵循现有代码模式
  • 简单安装：在 .gitlab-ci.yml 添加一个 Job，设置一个 masked CI/CD 变量
  • 企业就绪：可选择 Claude API、Amazon Bedrock 或 Google Vertex AI 来满足数据驻留和采购需求
  • 默认安全：代码运行在你的 GitLab runner 中，变更通过 MR 提交

工作原理

Claude Code 通过 GitLab CI/CD 在隔离 Job 中执行 AI 任务并将结果以 MR 方式提交：

  1. 事件驱动编排：GitLab 监听你选择的触发器（例如 Issue、MR 或评审线程中的 @claude 提及）。Job 收集线程和仓库上下文，构建提示，驱动 Claude Code。
  2. Provider 抽象：使用适合你环境的 provider：
    • Claude API（SaaS）
    • Amazon Bedrock（基于 IAM 访问，跨区域选项）
    • Google Vertex AI（GCP 原生，Workload Identity Federation）
  3. 沙箱执行：每次交互在容器中运行，具有严格的网络和文件系统规则。Claude Code 使用工作区范围权限限制写入。所有变更通过 MR 提交，审查者可以看到 diff，审批规则继续生效。

Claude 能做哪些事情

  • 从 Issue 描述或评论中创建和更新 MR
  • 分析性能回归并提出优化方案
  • 在分支中直接实现功能，然后打开 MR
  • 修复测试或评论发现的 Bug 和回归问题
  • 响应后续评论来迭代变更

安装

快速安装

  1. 添加 masked CI/CD 变量：Settings → CI/CD → Variables，添加 ANTHROPIC_API_KEY（masked，需要时 protected）

  2. 在 .gitlab-ci.yml 中添加 Claude Job：

stages:
  - ai

claude:
  stage: ai
  image: node:24-alpine3.21
  # 根据触发方式调整 rules：
  # - 手动触发
  # - MR 事件
  # - Web/API 触发（评论包含 @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
    - curl -fsSL https://claude.ai/install.sh | bash
  script:
    # 可选：启动 GitLab MCP 服务器（如果已配置）
    - /bin/gitlab-mcp-server || true
    # 通过 Web/API 触发时可以使用 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

添加 Job 和 ANTHROPIC_API_KEY 变量后，可从 CI/CD → Pipelines 手动运行 Job 测试，或通过 MR 触发，让 Claude 在分支中提出更新并打开 MR。

如果需要使用 Amazon Bedrock 或 Google Vertex AI 而非 Claude API，请参阅下方 基于 Amazon Bedrock 和 Google Vertex AI 的配置 章节，了解认证和环境设置。

手动安装（推荐用于生产）

  1. 配置 provider 访问：

    • Claude API：将 ANTHROPIC_API_KEY 存为 masked CI/CD 变量
    • Amazon Bedrock：配置 GitLab → AWS OIDC，创建 IAM 角色，授予 Bedrock 访问权限
    • Google Vertex AI：配置 Workload Identity Federation for GitLab → GCP

  2. 添加 GitLab API 凭据：

    • 默认使用 CI_JOB_TOKEN；或创建具有 api 范围的 Project Access Token，存为 GITLAB_ACCESS_TOKEN（masked）

  3. 将 Claude Job 添加到 .gitlab-ci.yml（参考下方配置示例）

  4. （可选）启用 @claude 提及触发：

    • 为项目的 “Comments (notes)” 事件添加 webhook 到事件监听器
    • 监听器在检测到评论包含 @claude 时，通过 Pipeline Trigger API 调用 pipeline，并传递 AI_FLOW_INPUT 和 AI_FLOW_CONTEXT 变量

使用示例

将 Issue 转为 MR

在 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

在 Issue 或 MR 评论中输入：

@claude fix the TypeError in the user dashboard component

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

基于 Amazon Bedrock 和 Google Vertex AI 的配置

Amazon Bedrock 配置

前置条件

  1. AWS 账户，Amazon Bedrock 已开通并可访问目标 Claude 模型
  2. GitLab 配置为 AWS IAM 的 OIDC 身份提供商
  3. IAM 角色具有 Bedrock 权限，信任策略限制到你的 GitLab 项目/分支
  4. CI/CD 变量用于角色假设：
    • AWS_ROLE_TO_ASSUME（角色 ARN）
    • AWS_REGION（Bedrock 区域）

设置步骤

  1. 启用 Amazon Bedrock，申请访问目标 Claude 模型
  2. 如果尚未创建，在 AWS 中为 GitLab 创建 IAM OIDC 提供商
  3. 创建 IAM 角色，信任 GitLab OIDC 提供商，限制到你的项目和保护分支
  4. 附加最低权限的 Bedrock invoke API 权限

需要存入 CI/CD 变量的值：

AWS_ROLE_TO_ASSUME
AWS_REGION

在 Settings → CI/CD → Variables 中添加。

运行时可参考下方 Amazon Bedrock Job 示例，用 GitLab Job token 交换临时 AWS 凭证。

Google Vertex AI 配置

前置条件

  1. GCP 项目：
    • Vertex AI API 已启用
    • Workload Identity Federation 已配置为信任 GitLab OIDC
  2. 专用服务账号，仅具备必要的 Vertex AI 角色
  3. CI/CD 变量：
    • GCP_WORKLOAD_IDENTITY_PROVIDER（完整资源名称）
    • GCP_SERVICE_ACCOUNT（服务账号邮箱）

设置步骤

  1. 启用 IAM Credentials API、STS API 和 Vertex AI API
  2. 创建 Workload Identity Pool 和 GitLab OIDC 提供商
  3. 创建专用服务账号并授予 Vertex AI 角色
  4. 授权 WIF 主体模拟该服务账号

需要存入 CI/CD 变量的值：

GCP_WORKLOAD_IDENTITY_PROVIDER
GCP_SERVICE_ACCOUNT
CLOUD_ML_REGION（例如 us-east5）

在 Settings → CI/CD → Variables 中添加。

运行时可参考下方 Google Vertex AI Job 示例，无需存储密钥即可完成认证。

配置示例

基本 .gitlab-ci.yml（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:-'Summarize recent changes and suggest improvements'}"
      --permission-mode acceptEdits
      --allowedTools "Bash Read Edit Write mcp__gitlab"
      --debug
  # Claude Code 会自动从 CI/CD 变量中读取 ANTHROPIC_API_KEY

Amazon Bedrock Job 示例（OIDC）

前置条件：

  • Amazon Bedrock 已启用，可访问目标 Claude 模型
  • GitLab OIDC 在 AWS 中已配置，IAM 角色信任你的项目和分支
  • IAM 角色具备最低权限的 Bedrock 权限

需要的 CI/CD 变量：

  • AWS_ROLE_TO_ASSUME：IAM 角色 ARN
  • AWS_REGION：Bedrock 区域（例如 us-west-2）
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:-'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"

Bedrock 的模型 ID 包含区域前缀（例如 us.anthropic.claude-sonnet-4-6）。可以通过 Job 配置或在 prompt 中指定目标模型。

Google Vertex AI Job 示例（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 区域（例如 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
    # 通过 WIF 认证（无需下载密钥）
    - >
      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
      )
    - gcloud config set project "$(gcloud projects list --format='value(projectId)' --filter="name:${CI_PROJECT_NAMESPACE}" | head -n1)" || true
  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"

使用 Workload Identity Federation 时无需存储服务账号密钥。建议使用仓库级别的信任条件和最低权限的服务账号。

最佳实践

CLAUDE.md 配置

在仓库根目录创建 CLAUDE.md，定义编码规范、审查标准和项目特定规则。Claude 在每次运行时读取此文件并遵循你的约定。

安全注意事项

永远不要在仓库中提交 API 密钥或云凭据。 始终使用 GitLab CI/CD 变量：

  • ANTHROPIC_API_KEY 应标记为 masked（如需要则 protected）
  • 尽可能使用 provider 级别的 OIDC（无长期密钥）
  • 限制 Job 权限和网络出站
  • 像对待普通贡献者一样审查 Claude 的 MR

性能优化

  • 保持 CLAUDE.md 内容聚焦且简洁
  • 提供清晰的 Issue/MR 描述以减少迭代次数
  • 设置合理的 Job 超时避免无限运行
  • 在 runner 中缓存 npm 和包安装

费用控制

使用 Claude Code 集成时需注意相关成本：

  • GitLab Runner 时间：Claude 运行在你的 runner 上，消耗计算分钟数。详见 GitLab 计划的 runner 计费说明。
  • API 费用：每次 Claude 交互根据 prompt 和 response 大小消耗 token。用量取决于任务复杂度和代码库大小。详见 Anthropic 定价。
  • 优化建议：
    • 使用具体的 @claude 命令减少不必要的回合
    • 设置合理的 max_turns 和 Job 超时值
    • 限制并发以控制并行运行数量

安全与治理

  • 每个 Job 在隔离容器中运行，网络访问受限制
  • Claude 的变更通过 MR 提交，审查者可以看到每个 diff
  • 分支保护和审批规则同样适用于 AI 生成的代码
  • Claude Code 使用工作区范围权限约束写入
  • 你掌控费用，因为你自己提供 provider 凭据

故障排查

Claude 不响应 @claude 命令

  • 确认 pipeline 是否被触发（手动、MR 事件或通过 note 事件监听器/webhook）
  • 确保 CI/CD 变量（ANTHROPIC_API_KEY 或云 provider 设置）存在且未被 mask 阻挡
  • 检查评论中包含的是 @claude（而非 /claude），且 mention 触发器已正确配置

Job 无法写入评论或打开 MR

  • 确保 CI_JOB_TOKEN 对项目具有足够权限；或使用具有 api 范围的 Project Access Token
  • 检查 --allowedTools 中是否包含 mcp__gitlab 工具
  • 确认 Job 运行在 MR 的上下文中，或通过 AI_FLOW_* 变量传递了足够的上下文

认证错误

  • Claude API：确认 ANTHROPIC_API_KEY 有效且未过期
  • Bedrock/Vertex：验证 OIDC/WIF 配置、角色模拟和 secret 名称；确认区域和模型可用性

进阶配置

常用参数和变量

Claude Code 支持以下常用输入：

  • prompt / prompt_file：内联（-p）或通过文件提供指令
  • max_turns：限制来回交互次数
  • timeout_minutes：限制总执行时间
  • ANTHROPIC_API_KEY：Claude API 必需（Bedrock/Vertex 不使用）
  • Provider 特定环境变量：AWS_REGION、CLOUD_ML_REGION 等

具体 flags 和参数可能因 @anthropic-ai/claude-code 的版本而异。在 Job 中运行 claude --help 查看支持选项。

自定义 Claude 的行为

可以通过两种方式指导 Claude：

  1. CLAUDE.md：定义编码规范、安全要求和项目约定。Claude 在运行时读取此文件并遵循规则。
  2. 自定义 prompt：通过 Job 中的 prompt/prompt_file 传递任务特定指令。可以为不同 Job 使用不同 prompt（例如 review、implement、refactor）。

常见问题

Claude Code GitLab 集成需要哪些 CI/CD 变量？

至少需要一个 API 密钥变量：选择 Claude API 则设置 ANTHROPIC_API_KEY；选择 Amazon Bedrock 则设置 AWS_ROLE_TO_ASSUME 和 AWS_REGION；选择 Google Vertex AI 则设置 GCP_WORKLOAD_IDENTITY_PROVIDER、GCP_SERVICE_ACCOUNT 和 CLOUD_ML_REGION。所有变量应在 GitLab CI/CD Settings 中标记为 masked。

@claude 不触发 MR 创建怎么办？

首先确认 pipeline 是否已触发：检查 CI/CD → Pipelines 是否有对应 Job 运行。如果 pipeline 未运行，检查 .gitlab-ci.yml 中的 rules 是否匹配你期望的触发条件（例如 $CI_PIPELINE_SOURCE == "web" 或 merge_request_event）。如果 pipeline 运行成功但未创建 MR，检查 Job 日志中 mcp__gitlab 工具是否可用，以及 CI_JOB_TOKEN 是否有足够权限（建议使用 api 范围的 Project Access Token）。

能否限制 Claude 只访问部分代码库？

可以。Claude Code 使用工作区作用域权限（通过 --permission-mode 和 --allowedTools 控制），并且默认容器内网络和文件系统受限制。此外，在 CLAUDE.md 中可以定义代码访问规则，例如“只修改 src/ 目录下的文件”。但请注意，这些限制依赖于 Claude 的遵循程度，生产环境中建议结合 GitLab 的分支保护规则和 MR 审批流程进行双重控制。