Claude Code GitLab CI/CD

Claude Code for GitLab CI/CD 目前處於測試版。隨著我們改進體驗，功能和功能可能會演變。此整合由 GitLab 維護。如需支援，請參閱以下 GitLab issue。

此整合建立在 Claude Code CLI and Agent SDK 之上，可在您的 CI/CD 工作和自訂自動化工作流程中以程式設計方式使用 Claude。

為什麼要在 GitLab 中使用 Claude Code？

即時 MR 建立：描述您需要的內容，Claude 會提出完整的 MR，包括變更和說明
自動化實現：使用單一命令或提及將問題轉變為可運作的程式碼
專案感知：Claude 遵循您的 CLAUDE.md 指南和現有程式碼模式
簡單設定：在 .gitlab-ci.yml 中新增一個工作和一個遮罩 CI/CD 變數
企業就緒：選擇 Claude API、Amazon Bedrock 或 Google Cloud 的 Agent Platform 以滿足資料駐留和採購需求
預設安全：在您的 GitLab runners 中執行，具有您的分支保護和核准

運作方式

Claude Code 使用 GitLab CI/CD 在隔離的工作中執行 AI 任務，並透過 MR 將結果提交回去：

事件驅動的編排：GitLab 監聽您選擇的觸發器（例如，在問題、MR 或審查執行緒中提及 @claude 的評論）。該工作從執行緒和儲存庫收集上下文，從該輸入建立提示，並執行 Claude Code。
提供者抽象化：使用適合您環境的提供者：
- Claude API (SaaS)
- Amazon Bedrock (基於 IAM 的存取、跨區域選項)
- Google Cloud 的 Agent Platform (GCP 原生、Workload Identity Federation)
沙箱執行：每次互動都在具有嚴格網路和檔案系統規則的容器中執行。Claude Code 強制執行工作區範圍的權限以限制寫入。每項變更都透過 MR 流動，以便審查者看到差異並且核准仍然適用。

選擇區域端點以減少延遲並滿足資料主權要求，同時使用現有的雲端協議。

Claude 可以做什麼？

Claude Code 啟用強大的 CI/CD 工作流程，改變您與程式碼的互動方式：

從問題描述或評論建立和更新 MR
分析效能回歸並提出最佳化建議
直接在分支中實現功能，然後開啟 MR
修復由測試或評論識別的錯誤和回歸
回應後續評論以反覆進行請求的變更

設定

快速設定

最快的入門方式是在您的 .gitlab-ci.yml 中新增最小工作，並將您的 API 金鑰設定為遮罩變數。

新增遮罩 CI/CD 變數
- 前往 Settings → CI/CD → Variables
- 新增 ANTHROPIC_API_KEY（遮罩，根據需要保護）
在 .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 server
    - /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，請參閱下方的 Using with Amazon Bedrock and Google Cloud 部分，了解驗證和環境設定。

手動設定（建議用於生產）

如果您偏好更受控的設定或需要企業提供者：

設定提供者存取：
- Claude API：建立並將 ANTHROPIC_API_KEY 儲存為遮罩 CI/CD 變數
- Amazon Bedrock：Configure GitLab → AWS OIDC 並為 Amazon Bedrock 建立 IAM 角色
- Google Cloud 的 Agent Platform：Configure Workload Identity Federation for GitLab → GCP
為 GitLab API 操作新增專案認證：
- 預設使用 CI_JOB_TOKEN，或建立具有 api 範圍的專案存取令牌
- 如果使用 PAT，將其儲存為 GITLAB_ACCESS_TOKEN（遮罩）
在 .gitlab-ci.yml 中新增 Claude 工作（請參閱下方的範例）
（選用）啟用提及驅動的觸發器：
- 為「Comments (notes)」新增專案 webhook 到您的事件監聽器（如果您使用的話）
- 當評論包含 @claude 時，讓監聽器使用 AI_FLOW_INPUT 和 AI_FLOW_CONTEXT 等變數呼叫管道觸發 API

範例使用案例

將問題轉變為 MR

在問題評論中：

@claude implement this feature based on the issue description

Claude 分析問題和程式碼庫，在分支中寫入變更，並開啟 MR 供審查。

獲得實現幫助

在 MR 討論中：

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

Claude 提出變更，新增具有適當快取的程式碼，並更新 MR。

快速修復錯誤

在問題或 MR 評論中：

@claude fix the TypeError in the user dashboard component

Claude 定位錯誤，實現修復，並更新分支或開啟新的 MR。

使用 Amazon Bedrock 和 Google Cloud

對於企業環境，您可以在您的雲端基礎設施上完全執行 Claude Code，具有相同的開發人員體驗。

Amazon Bedrock
Google Cloud's Agent Platform

先決條件

在使用 Amazon Bedrock 設定 Claude Code 之前，您需要：

具有 Amazon Bedrock 存取權限的 AWS 帳戶，可存取所需的 Claude 模型
在 AWS IAM 中設定為 OIDC 身份提供者的 GitLab
具有 Amazon Bedrock 權限和信任政策的 IAM 角色，限制於您的 GitLab 專案/refs
用於角色假設的 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 角色，限制於您的專案和受保護的 refs
為 Amazon Bedrock invoke API 附加最小權限

要儲存在 CI/CD 變數中的必需值：

AWS_ROLE_TO_ASSUME
AWS_REGION

在 Settings → CI/CD → Variables 中新增變數：

# 對於 Amazon Bedrock：
- AWS_ROLE_TO_ASSUME
- AWS_REGION

使用上面的 Amazon Bedrock 工作範例在執行時交換 GitLab 工作令牌以取得臨時 AWS 認證。

先決條件

在使用 Google Cloud’s Agent Platform 設定 Claude Code 之前，您需要：

具有以下內容的 Google Cloud 專案：
- 啟用 Google Cloud’s Agent Platform API
- 設定 Workload Identity Federation 以信任 GitLab OIDC
僅具有所需 Google Cloud’s Agent Platform 角色的專用服務帳戶
用於 WIF 的 GitLab CI/CD 變數：
- GCP_WORKLOAD_IDENTITY_PROVIDER（完整資源名稱）
- GCP_SERVICE_ACCOUNT（服務帳戶電子郵件）

設定說明

設定 Google Cloud 以允許 GitLab CI 工作透過 Workload Identity Federation 模擬服務帳戶。必需的設定：

啟用 IAM Credentials API、STS API 和 Google Cloud’s Agent Platform API
為 GitLab OIDC 建立 Workload Identity Pool 和提供者
建立具有 Google Cloud’s Agent Platform 角色的專用服務帳戶
授予 WIF 主體權限以模擬服務帳戶

要儲存在 CI/CD 變數中的必需值：

GCP_WORKLOAD_IDENTITY_PROVIDER
GCP_SERVICE_ACCOUNT

在 Settings → CI/CD → Variables 中新增變數：

# 對於 Google Cloud's Agent Platform：
- GCP_WORKLOAD_IDENTITY_PROVIDER
- GCP_SERVICE_ACCOUNT
- CLOUD_ML_REGION (例如，us-east5)

使用上面的 Google Cloud’s Agent Platform 工作範例在不儲存金鑰的情況下進行驗證。

設定範例

以下是您可以調整到您的管道的現成程式碼片段。

基本 .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 OIDC，具有信任您的 GitLab 專案和 refs 的角色
具有 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"

Amazon Bedrock 的模型 ID 包括區域特定的前綴（例如，us.anthropic.claude-sonnet-4-6）。如果您的工作流程支援，透過您的工作設定或提示傳遞所需的模型。

Agent Platform 工作範例 (Workload Identity Federation)

先決條件：

在您的 GCP 專案中啟用 Google Cloud 的 Agent Platform API
設定 Workload Identity Federation 以信任 GitLab OIDC
具有 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"

使用 Workload Identity Federation，您不需要儲存服務帳戶金鑰。使用儲存庫特定的信任條件和最小權限服務帳戶。

最佳實踐

CLAUDE.md 設定

在儲存庫根目錄建立 CLAUDE.md 檔案以定義編碼標準、審查標準和專案特定規則。Claude 在執行期間讀取此檔案並在提出變更時遵循您的慣例。

安全考量

永遠不要將 API 金鑰或雲端認證提交到您的儲存庫。始終使用 GitLab CI/CD 變數：

將 ANTHROPIC_API_KEY 新增為遮罩變數（並根據需要保護它）
盡可能使用提供者特定的 OIDC（無長期金鑰）
限制工作權限和網路出口
像審查任何其他貢獻者一樣審查 Claude 的 MR

最佳化效能

保持 CLAUDE.md 專注和簡潔
提供清晰的問題/MR 描述以減少反覆
設定合理的工作逾時以避免失控執行
在可能的情況下在 runners 中快取 npm 和套件安裝

CI 成本

使用 Claude Code 與 GitLab CI/CD 時，請注意相關成本：

GitLab Runner 時間：
- Claude 在您的 GitLab runners 上執行並消耗計算分鐘數
- 有關詳細資訊，請參閱您的 GitLab 計畫的 runner 計費
API 成本：
- 每次 Claude 互動根據提示和回應大小消耗令牌
- 令牌使用量因任務複雜性和程式碼庫大小而異
- 有關詳細資訊，請參閱 Anthropic 定價
成本最佳化提示：
- 使用特定的 @claude 命令以減少不必要的轉換
- 設定適當的 max_turns 和工作逾時值
- 限制並行以控制平行執行

安全和治理

每個工作都在具有受限網路存取的隔離容器中執行
Claude 的變更透過 MR 流動，以便審查者看到每個差異
分支保護和核准規則適用於 AI 生成的程式碼
Claude Code 使用工作區範圍的權限以限制寫入
成本保持在您的控制下，因為您帶來自己的提供者認證

疑難排解

Claude 不回應 @claude 命令

驗證您的管道正在被觸發（手動、MR 事件或透過 note 事件監聽器/webhook）
確保 CI/CD 變數（ANTHROPIC_API_KEY 或雲端提供者設定）存在且未遮罩
檢查評論是否包含 @claude（不是 /claude）以及您的提及觸發器是否已設定

工作無法寫入評論或開啟 MR

確保 CI_JOB_TOKEN 對專案具有足夠的權限，或使用具有 api 範圍的專案存取令牌
檢查 mcp__gitlab 工具是否在 --allowedTools 中啟用
確認工作在 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 的專案/區域變數

確切的旗標和參數可能因 @anthropic-ai/claude-code 的版本而異。在您的工作中執行 claude --help 以查看支援的選項。

自訂 Claude 的行為

您可以透過兩種主要方式指導 Claude：

CLAUDE.md：定義編碼標準、安全要求和專案慣例。Claude 在執行期間讀取此檔案並遵循您的規則。
自訂提示：透過工作中的 prompt/prompt_file 傳遞任務特定的說明。為不同的工作使用不同的提示（例如，審查、實現、重構）。

開始使用

核心概念

使用 Claude Code

平台與整合

為什麼要在 GitLab 中使用 Claude Code？

運作方式

Claude 可以做什麼？

設定

快速設定

手動設定（建議用於生產）

範例使用案例

將問題轉變為 MR

獲得實現幫助

快速修復錯誤

使用 Amazon Bedrock 和 Google Cloud

先決條件

設定說明

先決條件

設定說明

設定範例

基本 .gitlab-ci.yml (Claude API)

Amazon Bedrock 工作範例 (OIDC)

Agent Platform 工作範例 (Workload Identity Federation)

最佳實踐

CLAUDE.md 設定

安全考量

最佳化效能

CI 成本

安全和治理

疑難排解

Claude 不回應 @claude 命令

工作無法寫入評論或開啟 MR

驗證錯誤

進階設定

常見參數和變數

自訂 Claude 的行為

​為什麼要在 GitLab 中使用 Claude Code？

​運作方式

​Claude 可以做什麼？

​設定

​快速設定

​手動設定（建議用於生產）

​範例使用案例

​將問題轉變為 MR

​獲得實現幫助

​快速修復錯誤

​使用 Amazon Bedrock 和 Google Cloud

​先決條件

​設定說明

​先決條件

​設定說明

​設定範例

​基本 .gitlab-ci.yml (Claude API)

​Amazon Bedrock 工作範例 (OIDC)

​Agent Platform 工作範例 (Workload Identity Federation)

​最佳實踐

​CLAUDE.md 設定

​安全考量

​最佳化效能

​CI 成本

​安全和治理

​疑難排解

​Claude 不回應 @claude 命令

​工作無法寫入評論或開啟 MR

​驗證錯誤

​進階設定

​常見參數和變數

​自訂 Claude 的行為

為什麼要在 GitLab 中使用 Claude Code？

運作方式

Claude 可以做什麼？

設定

快速設定

手動設定（建議用於生產）

範例使用案例

將問題轉變為 MR

獲得實現幫助

快速修復錯誤

使用 Amazon Bedrock 和 Google Cloud

先決條件

設定說明

先決條件

設定說明

設定範例

基本 .gitlab-ci.yml (Claude API)

Amazon Bedrock 工作範例 (OIDC)

Agent Platform 工作範例 (Workload Identity Federation)

最佳實踐

CLAUDE.md 設定

安全考量

最佳化效能

CI 成本

安全和治理

疑難排解

Claude 不回應 @claude 命令

工作無法寫入評論或開啟 MR

驗證錯誤

進階設定

常見參數和變數

自訂 Claude 的行為