Claude Code GitLab CI/CD

了解如何通过 GitLab CI/CD 将 Claude Code 集成到您的开发工作流中

为何在 GitLab 中使用 Claude Code？

• 即时创建 MR：描述您的需求，Claude 即可提议包含更改和说明的完整 MR
• 自动化实现：通过单一命令或提及将 issue 转化为可运行的代码
• 项目感知：Claude 遵循您的 CLAUDE.md 指南和现有代码模式
• 简单设置：向 .gitlab-ci.yml 添加一个作业并设置一个 masked CI/CD 变量
• 企业就绪：选择 Claude API、Amazon Bedrock 或 Google Cloud 的 Agent Platform 以满足数据驻留和采购需求
• 默认安全：在您的 GitLab 运行器中运行，遵循您的分支保护和审批规则

工作原理

Claude Code 使用 GitLab CI/CD 在隔离作业中运行 AI 任务，并通过 MR 提交结果：

1. 事件驱动编排：GitLab 监听您选择的触发器（例如，在 issue、MR 或审查线程中提及 @claude 的评论）。作业收集线程和仓库的上下文，从该输入构建 prompt，并运行 Claude Code。

2. 提供商抽象：使用适合您环境的提供商：

   • Claude API（SaaS）
   • Amazon Bedrock（基于 IAM 的访问，跨区域选项）
   • Google Cloud 的 Agent Platform（GCP 原生，Workload Identity Federation）

3. 沙箱执行：每次交互在具有严格网络和文件系统规则的容器中运行。Claude Code 强制执行工作空间范围的权限以约束写入。每项更改都通过 MR 流转，以便审查者查看差异且审批规则仍然适用。

选择区域端点以减少延迟并满足数据主权要求，同时使用现有的云协议。

Claude 能做什么？

Claude Code 支持强大的 CI/CD 工作流，彻底改变您处理代码的方式：

• 从 issue 描述或评论创建和更新 MR
• 分析性能回归并提出优化建议
• 直接在分支中实现功能，然后打开 MR
• 修复测试或评论识别的错误和回归
• 响应后续评论以迭代请求的更改

设置

快速设置

入门最快的方式是向 .gitlab-ci.yml 添加一个最小作业，并将您的 API 密钥设置为 masked 变量。

1. 添加 masked CI/CD 变量

   • 前往 Settings → CI/CD → Variables
   • 添加 ANTHROPIC_API_KEY（根据需要设置为 masked、protected）

2. 向 .gitlab-ci.yml 添加 Claude 作业

stages:
  - ai

claude:
  stage: ai
  image: node:24-alpine3.21
  # 调整规则以符合您希望触发作业的方式：
  # - 手动运行
  # - 合并请求事件
  # - 评论包含 '@claude' 时的 Web/API 触发器
  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_* 变量和上下文 payload
    - 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

添加作业和 ANTHROPIC_API_KEY 变量后，通过从 CI/CD → Pipelines 手动运行作业来测试，或从 MR 触发它以让 Claude 在分支中提议更新并在需要时打开 MR。

手动设置（推荐用于生产环境）

如果您偏好更受控的设置或需要企业提供商：

1. 配置提供商访问：

   • Claude API：创建并存储 ANTHROPIC_API_KEY 作为 masked CI/CD 变量
   • Amazon Bedrock：配置 GitLab → AWS OIDC 并创建用于 Amazon Bedrock 的 IAM 角色
   • Google Cloud 的 Agent Platform：配置适用于 GitLab 的 Workload Identity Federation → GCP

2. 添加用于 GitLab API 操作的项目凭证：

   • 默认使用 CI_JOB_TOKEN，或使用具有 api 范围的 Project Access Token
   • 如果使用 PAT，则存储为 GITLAB_ACCESS_TOKEN（masked）

3. 向 .gitlab-ci.yml 添加 Claude 作业（请参阅下面的示例）

4. （可选）启用提及驱动触发器：

   • 为 "Comments (notes)" 添加项目 webhook 到您的事件监听器（如果使用）
   • 让监听器在评论包含 @claude 时调用流水线触发 API，并传递 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。

快速修复错误

在 issue 或 MR 评论中：

@claude fix the TypeError in the user dashboard component

Claude 定位错误，实施修复，并更新分支或打开新的 MR。

与 Amazon Bedrock 和 Google Cloud 配合使用

对于企业环境，您可以在自有云基础设施上完全运行 Claude Code，保持相同的开发者体验。

# 对于 Amazon Bedrock：
- AWS_ROLE_TO_ASSUME
- AWS_REGION

# 对于 Google Cloud 的 Agent Platform：
- GCP_WORKLOAD_IDENTITY_PROVIDER
- GCP_SERVICE_ACCOUNT
- CLOUD_ML_REGION（例如 us-east5）

配置示例

以下是您可以适配到流水线的现成代码片段。

基础 .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 作业示例（OIDC）

前提条件：

• 已启用 Amazon Bedrock 并可访问您选择的 Claude 模型
• 在 AWS 中配置了信任您的 GitLab 项目和 refs 的 GitLab OIDC
• 具有 Amazon Bedrock 权限的 IAM 角色（建议最小权限）

所需的 CI/CD 变量：

• AWS_ROLE_TO_ASSUME：用于 Amazon Bedrock 访问的 IAM 角色 ARN
• AWS_REGION：Amazon 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 令牌以获取 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"

Agent Platform 作业示例（Workload Identity Federation）

前提条件：

• 在您的 GCP 项目中启用了 Google Cloud 的 Agent Platform API
• 配置了信任 GitLab OIDC 的 Workload Identity Federation
• 具有 Google Cloud 的 Agent Platform 权限的服务账号

所需的 CI/CD 变量：

• GCP_WORKLOAD_IDENTITY_PROVIDER：完整提供商资源名称
• GCP_SERVICE_ACCOUNT：服务账号电子邮件
• CLOUD_ML_REGION：Google Cloud 的 Agent Platform 区域（例如 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 向 Google Cloud 进行身份验证（无需下载密钥）
    - >
      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"

最佳实践

CLAUDE.md 配置

在仓库根目录创建 CLAUDE.md 文件，以定义编码标准、审查标准和项目特定规则。Claude 在运行期间读取此文件，并在提议更改时遵循您的约定。

安全注意事项

切勿将 API 密钥或云凭证提交到您的仓库。始终使用 GitLab CI/CD 变量：

• 将 ANTHROPIC_API_KEY 添加为 masked 变量（并根据需要保护）
• 尽可能使用提供商特定的 OIDC（无需长期密钥）
• 限制作业权限和网络出口
• 像审查任何其他贡献者一样审查 Claude 的 MR

优化性能

• 保持 CLAUDE.md 聚焦且简洁
• 提供清晰的 issue/MR 描述以减少迭代
• 配置合理的作业超时以避免失控运行
• 尽可能在运行器中缓存 npm 和包安装

CI 成本

使用 Claude Code 与 GitLab CI/CD 时，请注意相关成本：

• GitLab Runner 时间：

  • Claude 在您的 GitLab 运行器上运行并消耗计算分钟数
  • 有关详情，请参阅您的 GitLab 计划的 runner 计费

• API 成本：

  • 每次 Claude 交互根据 prompt 和响应大小消耗 token
  • Token 使用量因任务复杂度和代码库大小而异
  • 有关详情，请参阅 Anthropic 定价

• 成本优化建议：

  • 使用特定的 @claude 命令以减少不必要的轮次
  • 设置适当的 max_turns 和作业超时值
  • 限制并发以控制并行运行

安全与治理

• 每个作业在具有受限网络访问的隔离容器中运行
• Claude 的更改通过 MR 流转，以便审查者查看每个差异
• 分支保护和审批规则适用于 AI 生成的代码
• Claude Code 使用工作空间范围的权限来约束写入
• 成本由您控制，因为您自带提供商凭证

故障排查

Claude 不响应 @claude 命令

• 验证您的流水线是否被触发（手动、MR 事件或通过备注事件监听器/webhook）
• 确保 CI/CD 变量（ANTHROPIC_API_KEY 或云提供商设置）存在且未 masked
• 检查评论包含 @claude（而非 /claude）且您的提及触发器已配置

作业无法写入评论或打开 MR

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

身份验证错误

• 对于 Claude API：确认 ANTHROPIC_API_KEY 有效且未过期
• 对于 Amazon Bedrock 或 Google Cloud 的 Agent Platform：验证 OIDC/WIF 配置、角色模拟和密钥名称；确认区域和模型可用性

高级配置

常用参数和变量

Claude Code 支持以下常用输入：

• prompt / prompt_file：内联提供指令 (-p) 或通过文件
• max_turns：限制来回迭代次数
• timeout_minutes：限制总执行时间
• ANTHROPIC_API_KEY：Claude API 所需（Amazon Bedrock 或 Google Cloud 的 Agent Platform 不使用）
• 提供商特定环境：AWS_REGION、Google Cloud 的 Agent Platform 的项目/区域变量

自定义 Claude 的行为

您可以通过两种主要方式引导 Claude：

1. CLAUDE.md：定义编码标准、安全要求和项目约定。Claude 在运行期间读取此文件并遵循您的规则。
2. 自定义 prompts：通过作业中的 prompt/prompt_file 传递任务特定指令。为不同的作业使用不同的 prompts（例如审查、实现、重构）。