GitLab CI/CD

在 GitLab CI/CD 里运行 Claude Code：快速与手动设置、@claude 触发、用例、Amazon Bedrock（OIDC）和 Google Cloud（WIF）作业示例、最佳实践、成本与排障（测试版，由 GitLab 维护）。

Claude Code for GitLab CI/CD 目前是测试版，功能可能变化。这个集成由 GitLab 维护，支持问题见 GitLab 的相关 issue。它建立在 Claude Code CLI 和 Agent SDK 之上，可以在你的 CI/CD 作业和自定义自动化里以编程方式使用 Claude。

为什么在 GitLab 里用 Claude Code

即时创建 MR：描述你的需求，Claude 提出带改动和说明的完整 MR。
自动实现：用一条命令或一次提及把 issue 变成可工作的代码。
了解项目：Claude 遵循你的 CLAUDE.md 规范和现有代码模式。
设置简单：往 .gitlab-ci.yml 加一个作业和一个被掩码的 CI/CD 变量。
企业就绪：可选 Claude API、Amazon Bedrock 或 Google Cloud 的 Agent Platform，满足数据驻留和采购需求。
默认安全：在你的 GitLab runner 上运行，沿用你的分支保护和审批。

工作方式

Claude Code 用 GitLab CI/CD 在隔离的作业里运行 AI 任务，并通过 MR 把结果提交回来：

事件驱动编排：GitLab 监听你选定的触发器（例如 issue、MR 或评审线程里提到 @claude 的评论）。作业从线程和仓库收集上下文，基于这些输入构建提示并运行 Claude Code。
提供商抽象：用适合你环境的提供商：Claude API（SaaS）、Amazon Bedrock（基于 IAM 的访问、跨区域选项）、Google Cloud 的 Agent Platform（GCP 原生，Workload Identity Federation）。
沙盒执行：每次交互都在有严格网络和文件系统规则的容器里运行。Claude Code 强制工作区范围的权限来约束写入。每个改动都经过 MR，所以评审者能看到 diff，审批仍然适用。

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

Claude 能做什么

在 GitLab 流水线里，Claude Code 可以：

根据 issue 描述或评论创建和更新 MR
分析性能回归并提出优化
直接在分支里实现功能，然后开 MR
修复测试或评论里指出的缺陷和回归
响应后续评论，迭代所要求的修改

设置

快速设置

最快的办法是往 .gitlab-ci.yml 加一个最小作业，并把 API key 设为被掩码的变量。

1. 添加被掩码的 CI/CD 变量：进入 Settings → CI/CD → Variables，添加 ANTHROPIC_API_KEY（掩码，按需保护）。

2. 往 .gitlab-ci.yml 添加 Claude 作业：

stages:
  - ai

claude:
  stage: ai
  image: node:24-alpine3.21
  # 调整 rules 以适应你想怎么触发这个作业：
  # - 手动运行
  # - 合并请求事件
  # - 评论包含 '@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
    # 安装器把 claude 放在 ~/.local/bin，这个镜像里它不在 PATH 上
    - export PATH="$HOME/.local/bin:$PATH"
  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

添加作业和 ANTHROPIC_API_KEY 变量后，在 CI/CD → Pipelines 里手动运行作业来测试，或在 MR 里触发它，让 Claude 在分支里提出更新并在需要时开 MR。要在 Amazon Bedrock 或 Google Cloud 的 Agent Platform 而不是 Claude API 上运行，见下面「配合 Amazon Bedrock 和 Google Cloud 使用」里的认证和环境设置。

手动设置（生产推荐）

想要更可控的设置或需要企业提供商时：

配置提供商访问：
- Claude API：创建 ANTHROPIC_API_KEY 并存为被掩码的 CI/CD 变量。
- Amazon Bedrock：配置 GitLab → AWS OIDC，并为 Amazon Bedrock 创建 IAM 角色。
- Google Cloud 的 Agent Platform：为 GitLab 配置 Workload Identity Federation → GCP。
为 GitLab API 操作添加项目凭据：默认使用 CI_JOB_TOKEN，或创建带 api 范围的 Project Access Token；使用 PAT 时存为被掩码的 GITLAB_ACCESS_TOKEN。
往 .gitlab-ci.yml 添加 Claude 作业：Claude API 用快速设置里的作业，提供商用「配置示例」里的作业。
（可选）启用提及驱动的触发器：给你的事件监听器添加项目 webhook「Comments (notes)」（如果你用监听器）；让监听器在评论含 @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

前提条件：

一个有所需 Claude 模型的 Amazon Bedrock 访问权的 AWS 账号。
在 AWS IAM 里把 GitLab 配置为 OIDC 身份提供商。
一个有 Amazon Bedrock 权限、信任策略限制到你的 GitLab 项目/引用的 IAM 角色。
用于角色扮演的 GitLab CI/CD 变量：AWS_ROLE_TO_ASSUME（角色 ARN）和 AWS_REGION（Amazon Bedrock 区域）。

设置： 配置 AWS，让 GitLab CI 作业经 OIDC 担任 IAM 角色（无静态密钥）。必要步骤：启用 Amazon Bedrock 并申请目标 Claude 模型的访问；如果还没有，创建 GitLab 的 IAM OIDC 提供商；创建受 GitLab OIDC 提供商信任、限制到你的项目和受保护引用的 IAM 角色；为 Amazon Bedrock 调用 API 附加最小权限。然后用下面的 Amazon Bedrock 作业示例在运行时把作业的 OIDC 令牌换成临时 AWS 凭据。

Google Cloud 的 Agent Platform

前提条件：

一个 Google Cloud 项目，其中启用了 Agent Platform API，并配置了信任 GitLab OIDC 的 Workload Identity Federation。
一个只有所需 Agent Platform 角色的专用服务账号。
GitLab CI/CD 变量：GCP_WORKLOAD_IDENTITY_PROVIDER（不带 //iam.googleapis.com/ 前缀的提供商资源名，如 projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider）、GCP_SERVICE_ACCOUNT（服务账号邮箱）、GCP_PROJECT_ID（Google Cloud 项目 ID）。

设置： 配置 Google Cloud，让 GitLab CI 作业经 Workload Identity Federation 模拟服务账号。必要步骤：启用 IAM Credentials API、STS API 和 Agent Platform API；为 GitLab OIDC 创建 Workload Identity Pool 和提供商；创建带 Agent Platform 角色的专用服务账号；授予 WIF 主体模拟该服务账号的权限。然后用下面的 Agent Platform 作业示例，无需存储密钥即可认证。

配置示例

下面是可以改造后用于你流水线的现成片段。

Amazon Bedrock 作业示例（OIDC）

前提：启用了 Amazon Bedrock 并有所选 Claude 模型的访问权；在 AWS 里配置了 GitLab OIDC，且有信任你的 GitLab 项目和引用的角色；有 Amazon Bedrock 权限的 IAM 角色（建议最小权限）。必需的 CI/CD 变量：AWS_ROLE_TO_ASSUME（Amazon Bedrock 访问用的 IAM 角色 ARN）和 AWS_REGION（如 us-west-2）。

GitLab 从 id_tokens: 块签发作业的 OIDC 令牌，并作为 GITLAB_OIDC_TOKEN 暴露。把 aud 设为你在 AWS 的 IAM OIDC 身份提供商上配置的受众值，例如你的 GitLab 实例 URL。

stages:
  - ai

claude-bedrock:
  stage: ai
  image: node:24-alpine3.21
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web"'
  id_tokens:
    GITLAB_OIDC_TOKEN:
      aud: https://gitlab.example.com
  before_script:
    - apk add --no-cache bash curl jq git aws-cli
    - curl -fsSL https://claude.ai/install.sh | bash
    # 安装器把 claude 放在 ~/.local/bin，这个镜像里它不在 PATH 上
    - export PATH="$HOME/.local/bin:$PATH"
    # 把作业的 OIDC 令牌换成 AWS 凭据
    - export AWS_WEB_IDENTITY_TOKEN_FILE="/tmp/oidc_token"
    - printf "%s" "$GITLAB_OIDC_TOKEN" > "$AWS_WEB_IDENTITY_TOKEN_FILE"
    - >
      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"
    CLAUDE_CODE_USE_BEDROCK: "1"

Amazon Bedrock 的模型 ID 带区域特定的前缀（例如 us.anthropic.claude-sonnet-4-6）；如果你的工作流支持，通过作业配置或提示传入想要的模型。

Agent Platform 作业示例（Workload Identity Federation）

前提：GCP 项目里启用了 Agent Platform API；配置了信任 GitLab OIDC 的 Workload Identity Federation；有 Agent Platform 权限的服务账号。必需的 CI/CD 变量：GCP_WORKLOAD_IDENTITY_PROVIDER、GCP_SERVICE_ACCOUNT、GCP_PROJECT_ID，以及 CLOUD_ML_REGION（Agent Platform 区域，如 us-east5）。

GitLab 从 id_tokens: 块签发作业的 OIDC 令牌并作为 GITLAB_OIDC_TOKEN 暴露；把 aud 设为你在 Workload Identity Pool 提供商上配置的受众值，例如你的 GitLab 实例 URL。作业把令牌写进文件，凭据配置的 credential_source 条目告诉 Google 的认证库从那里读取；把 GOOGLE_APPLICATION_CREDENTIALS 设为凭据配置文件，就能经 Application Default Credentials 让 Claude Code 使用它。

stages:
  - ai

claude-vertex:
  stage: ai
  image: gcr.io/google.com/cloudsdktool/google-cloud-cli:slim
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web"'
  id_tokens:
    GITLAB_OIDC_TOKEN:
      aud: https://gitlab.example.com
  before_script:
    - apt-get update && apt-get install -y git && apt-get clean
    - curl -fsSL https://claude.ai/install.sh | bash
    # 安装器把 claude 放在 ~/.local/bin，这个镜像里它不在 PATH 上
    - export PATH="$HOME/.local/bin:$PATH"
    # 把作业的 OIDC 令牌写到 credential_source 期望的位置
    - printf "%s" "$GITLAB_OIDC_TOKEN" > /tmp/oidc_token
    # 把 WIF 凭据配置写到文件（不下载密钥）
    - |
      cat > /tmp/cred.json <<EOF
      {
        "type": "external_account",
        "audience": "//iam.googleapis.com/${GCP_WORKLOAD_IDENTITY_PROVIDER}",
        "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
        "token_url": "https://sts.googleapis.com/v1/token",
        "credential_source": {
          "file": "/tmp/oidc_token"
        },
        "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/${GCP_SERVICE_ACCOUNT}:generateAccessToken"
      }
      EOF
    # 经 Application Default Credentials 把凭据暴露给 Claude Code
    - export GOOGLE_APPLICATION_CREDENTIALS=/tmp/cred.json
    # 用同一份凭据配置认证 gcloud CLI
    - gcloud auth login --cred-file=/tmp/cred.json
    - gcloud config set project "$GCP_PROJECT_ID"
  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_CODE_USE_VERTEX: "1"
    ANTHROPIC_VERTEX_PROJECT_ID: "$GCP_PROJECT_ID"

用了 Workload Identity Federation 就不需要存服务账号密钥；使用针对仓库的信任条件和最小权限的服务账号。

最佳实践

CLAUDE.md 配置

在仓库根目录创建 CLAUDE.md，定义编码规范、评审标准和项目特定规则。Claude 在运行期间读取它，并在提出改动时遵循你的约定。

安全考虑

绝不要把 API key 或云凭据提交到仓库。 一律使用 GitLab CI/CD 变量：

把 ANTHROPIC_API_KEY 添加为被掩码的变量（按需保护）
尽可能使用提供商特定的 OIDC（没有长期密钥）
限制作业权限和网络出口
像评审其他贡献者的改动一样评审 Claude 的 MR

优化性能

保持 CLAUDE.md 聚焦、简洁
提供清晰的 issue/MR 描述以减少迭代
尽可能在 runner 上缓存 npm 和软件包安装

CI 成本

在 GitLab CI/CD 里使用 Claude Code 要注意相关成本：

GitLab Runner 时间：Claude 在你的 GitLab runner 上运行并消耗计算分钟，详情见你的 GitLab 套餐的 runner 计费。
API 成本：每次 Claude 交互按提示和响应大小消耗 token，用量随任务复杂度和代码库大小而变，价格以官方定价页为准。
成本优化建议：用具体的 @claude 命令减少不必要的轮次；设置合适的 --max-turns 和作业 timeout 值；限制并发以控制并行运行。

排障

Claude 没有响应 @claude 命令

确认你的流水线被触发了（手动、MR 事件，或经评论事件监听器/webhook）。
确保 ANTHROPIC_API_KEY 或云提供商变量存在。
检查评论含的是 @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 配置、角色模拟和密钥名称；确认区域和模型可用。

高级配置

常用参数和变量

用这些 CLI 标志、GitLab 关键字和变量控制作业里的 Claude Code 运行：

-p：内联提供指令，例如 claude -p "Review this MR"
--max-turns：限制来回迭代的次数
timeout：用 GitLab 作业级的 timeout 关键字限制作业总执行时间，如 timeout: 30m
ANTHROPIC_API_KEY：Claude API 必需（Amazon Bedrock 或 Google Cloud 的 Agent Platform 不使用）
提供商特定的环境：AWS_REGION，以及 Agent Platform 的项目/区域变量

具体的标志和参数可能随 @anthropic-ai/claude-code 的版本而变，在作业里运行 claude --help 查看支持的选项。

自定义 Claude 的行为

主要有两种引导方式：

CLAUDE.md：定义编码规范、安全要求和项目约定，Claude 在运行期间读取并遵循。
自定义提示：在作业里通过 -p 传入任务特定的指令；不同作业用不同提示（如评审、实现、重构）。