Claude Code GitLab CI/CD 集成

Claude Code 与 GitLab CI/CD 集成，让 AI 直接参与开发流程：在 Issue 或 MR 中 @claude，Claude 分析代码、创建分支、实现功能或修复 Bug，变更通过 MR 流程提交，所有审批规则正常生效。支持 Claude API（直连）、AWS Bedrock（IAM OIDC）和 Google Vertex AI（Workload Identity Federation）三种认证方式，无需长期密钥。通过添加一个 GitLab CI/CD Job 即可快速接入。

Claude Code 与 GitLab CI/CD 集成，将 AI 自动化引入你的开发流程。

核心优势：

即时 MR 创建：描述需求，Claude 创建包含变更和说明的完整 MR
自动实现：Issue 转工作代码，一条命令或一次提及即可
项目感知：读取 CLAUDE.md 规范和现有代码模式
简单安装：在 .gitlab-ci.yml 添加一个 Job，设置 API Key 变量
企业就绪：支持 Claude API、AWS Bedrock 或 Google Vertex AI
默认安全：在你的 GitLab runners 中运行，变更通过 MR 审批

工作原理

事件驱动编排：GitLab 监听触发条件（如 Issue/MR/评审线程中的 @claude 提及），收集上下文，构建提示词，运行 Claude Code
Provider 抽象：选择适合你环境的 provider——Claude API（SaaS）、AWS Bedrock（IAM）或 Google Vertex AI（GCP 原生）
沙箱执行：每次交互在容器中运行，带严格的网络和文件系统规则。所有变更通过 MR 提交，审批照常生效

Claude 能做什么

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

安装

快速安装

添加 CI/CD 变量：Settings → CI/CD → Variables，添加 ANTHROPIC_API_KEY（标记为 masked）
在 .gitlab-ci.yml 中添加 Claude Job：

yaml

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:-'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 手动运行测试，或通过 MR 触发，让 Claude 在分支中提出更新并打开 MR。

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

配置 Provider 访问：
- Claude API：将 ANTHROPIC_API_KEY 存为 masked CI/CD 变量
- AWS Bedrock：配置 GitLab → AWS OIDC，创建 IAM 角色
- Google Vertex AI：配置 Workload Identity Federation
添加 GitLab API 凭据：
- 默认使用 CI_JOB_TOKEN，或创建 api 范围的 Project Access Token 存为 GITLAB_ACCESS_TOKEN
添加 Claude Job 到 .gitlab-ci.yml
（可选）启用 mention 驱动触发：
- 为 "Comments (notes)" 事件添加 webhook
- 接收到包含 @claude 的评论时，通过 pipeline trigger API 传入 AI_FLOW_INPUT 等变量

使用示例

将 Issue 转为 MR

@claude implement this feature based on the issue description

Claude 分析 Issue 和代码库，在分支中写入变更，打开 MR 供审查。

获取实现建议

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

快速修复 Bug

@claude fix the TypeError in the user dashboard component

使用 AWS Bedrock

前置条件：

AWS 账户开启 Amazon Bedrock 和目标 Claude 模型访问权限
GitLab 配置为 AWS IAM 的 OIDC 身份提供商
IAM 角色具有 Bedrock 权限，信任策略限制到你的 GitLab 项目/分支
CI/CD 变量：AWS_ROLE_TO_ASSUME（角色 ARN）、AWS_REGION（Bedrock 区域）

AWS Bedrock Job 示例（OIDC）：

yaml

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"

使用 Google Vertex AI

前置条件：

GCP 项目开启 Vertex AI API
为 GitLab OIDC 配置 Workload Identity Federation
服务账号具有 Vertex AI 权限
CI/CD 变量：GCP_WORKLOAD_IDENTITY_PROVIDER、GCP_SERVICE_ACCOUNT、CLOUD_ML_REGION

Google Vertex AI Job 示例（WIF）：

yaml

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
      )
  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 Key 或云凭据。**始终使用 GitLab CI/CD 变量：

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

费用控制

GitLab Runner 时间：消耗计算分钟数
API 费用：每次交互消耗 token，用量取决于任务复杂度

优化建议：

使用具体的 @claude 命令减少不必要的轮次
设置合理的 max_turns 和 Job 超时
限制并发控制并行运行数量
尽可能缓存 npm 和包安装

安全与治理

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

故障排查

问题	检查点
Claude 不响应 @claude	确认 Pipeline 已触发、CI/CD 变量已设置且未被 mask 阻挡、评论包含 `@claude` 而非 `/claude`、mention 触发已配置
GitLab MCP 工具不起作用	确认 `CI_JOB_TOKEN` 权限足够，或使用具有 `api` 范围的 PAT；检查 `mcp__gitlab` 在 `--allowedTools` 中已启用
认证错误	Claude API：确认 Key 有效；Bedrock/Vertex：验证 OIDC/WIF 配置、角色冒充和 Secret 名称，确认区域和模型可用性

常见问题

Q: 使用 GitLab 集成需要特别的权限吗？

CI_JOB_TOKEN 通常就够了。如果需要更多 GitLab API 操作（如创建 MR、管理分支），可以创建具有 api 范围的 Project Access Token，存为 GITLAB_ACCESS_TOKEN 变量。

Q: AWS Bedrock 和 Google Vertex AI 集成安全吗？不需要长期密钥？

对。两种方式都通过 OIDC/Workload Identity Federation 实现，GitLab CI Job token 换取临时云凭据，不需要在变量中存储长期的 AWS Access Key 或 GCP 服务账号密钥文件。

Q: Claude 创建的 MR 会绕过分支保护规则吗？

不会。Claude 的变更通过标准 MR 流程提交，所有分支保护规则、审批要求和 CI 检查照常生效。AI 生成的代码和人工代码受到相同的治理约束。

Claude Code GitLab CI/CD 集成 ​

工作原理 ​

Claude 能做什么 ​

安装 ​

快速安装 ​

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

使用示例 ​

将 Issue 转为 MR ​

获取实现建议 ​

快速修复 Bug ​

使用 AWS Bedrock ​

使用 Google Vertex AI ​

最佳实践 ​

CLAUDE.md 配置 ​

安全注意事项 ​

费用控制 ​

安全与治理 ​

故障排查 ​

相关文档 ​

常见问题 ​

Claude Code GitLab CI/CD 集成

工作原理

Claude 能做什么

安装

快速安装

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

使用示例

将 Issue 转为 MR

获取实现建议

快速修复 Bug

使用 AWS Bedrock

使用 Google Vertex AI

最佳实践

CLAUDE.md 配置

安全注意事项

费用控制

安全与治理

故障排查

相关文档

常见问题