Claude Code GitLab CI/CD

Claude Code for GitLab CI/CD 目前處於測試版階段。隨著我們不斷改進體驗，功能和特性可能會有所變化。

此整合由 GitLab 維護。如需支援，請參閱以下 GitLab issue。

此整合建立在 Claude Code CLI 和 SDK 之上，讓您能在 CI/CD 作業和自訂自動化工作流程中以程式化方式使用 Claude。

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

即時 MR 建立：描述您的需求，Claude 會提出包含變更和說明的完整 MR
自動化實作：透過單一指令或提及將 issue 轉換為可運作的程式碼
專案感知：Claude 遵循您的 CLAUDE.md 指導原則和現有程式碼模式
簡單設定：在 .gitlab-ci.yml 中新增一個作業和一個遮罩的 CI/CD 變數
企業就緒：選擇 Anthropic API、AWS Bedrock 或 Google Vertex AI 以滿足資料駐留和採購需求
預設安全：在您的 GitLab runner 中執行，具備分支保護和核准機制

運作原理

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

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

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

Claude 能做什麼？

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

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

設定

快速設定

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

新增遮罩的 CI/CD 變數
- 前往設定 → CI/CD → 變數
- 新增 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
    - npm install -g @anthropic-ai/claude-code
  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 → 管線手動執行作業進行測試，或從 MR 觸發它，讓 Claude 在分支中提出更新並視需要開啟 MR。

要在 AWS Bedrock 或 Google Vertex AI 上執行而非 Anthropic API，請參閱下方的使用 AWS Bedrock 和 Google Vertex AI 部分以了解驗證和環境設定。

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

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

設定提供者存取：
- Anthropic API：建立並儲存 ANTHROPIC_API_KEY 作為遮罩的 CI/CD 變數
- AWS Bedrock：設定 GitLab → AWS OIDC 並為 Bedrock 建立 IAM 角色
- Google Vertex AI：為 GitLab 設定 Workload Identity Federation → GCP
為 GitLab API 操作新增專案憑證：
- 預設使用 CI_JOB_TOKEN，或建立具有 api 範圍的專案存取權杖
- 如果使用 PAT，請儲存為 GITLAB_ACCESS_TOKEN（遮罩）
在 .gitlab-ci.yml 中新增 Claude 作業（請參閱下方範例）
（可選）啟用提及驅動的觸發器：
- 為您的事件監聽器（如果您使用）新增「評論（註記）」的專案 webhook
- 當評論包含 @claude 時，讓監聽器使用 AI_FLOW_INPUT 和 AI_FLOW_CONTEXT 等變數呼叫管線觸發 API

範例使用案例

將 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。

使用 AWS Bedrock 和 Google Vertex AI

對於企業環境，您可以在自己的雲端基礎設施上完全執行 Claude Code，同時保持相同的開發者體驗。

先決條件

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

具有 Amazon Bedrock 存取權限的 AWS 帳戶，可存取所需的 Claude 模型
在 AWS IAM 中設定為 OIDC 身分提供者的 GitLab
具有 Bedrock 權限和信任政策的 IAM 角色，限制於您的 GitLab 專案/參考
用於角色假設的 GitLab CI/CD 變數：
- AWS_ROLE_TO_ASSUME（角色 ARN）
- AWS_REGION（Bedrock 區域）

設定說明

設定 AWS 以允許 GitLab CI 作業透過 OIDC 假設 IAM 角色（無靜態金鑰）。

必要設定：

啟用 Amazon Bedrock 並請求存取您的目標 Claude 模型
如果尚未存在，為 GitLab 建立 IAM OIDC 提供者
建立由 GitLab OIDC 提供者信任的 IAM 角色，限制於您的專案和受保護的參考
附加 Bedrock 調用 API 的最小權限

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

AWS_ROLE_TO_ASSUME
AWS_REGION

在設定 → CI/CD → 變數中新增變數：

# 對於 AWS Bedrock：
- AWS_ROLE_TO_ASSUME
- AWS_REGION

使用上方的 AWS Bedrock 作業範例在執行時將 GitLab 作業權杖交換為臨時 AWS 憑證。

先決條件

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

具有 Amazon Bedrock 存取權限的 AWS 帳戶，可存取所需的 Claude 模型
在 AWS IAM 中設定為 OIDC 身分提供者的 GitLab
具有 Bedrock 權限和信任政策的 IAM 角色，限制於您的 GitLab 專案/參考
用於角色假設的 GitLab CI/CD 變數：
- AWS_ROLE_TO_ASSUME（角色 ARN）
- AWS_REGION（Bedrock 區域）

設定說明

設定 AWS 以允許 GitLab CI 作業透過 OIDC 假設 IAM 角色（無靜態金鑰）。

必要設定：

啟用 Amazon Bedrock 並請求存取您的目標 Claude 模型
如果尚未存在，為 GitLab 建立 IAM OIDC 提供者
建立由 GitLab OIDC 提供者信任的 IAM 角色，限制於您的專案和受保護的參考
附加 Bedrock 調用 API 的最小權限

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

AWS_ROLE_TO_ASSUME
AWS_REGION

在設定 → CI/CD → 變數中新增變數：

# 對於 AWS Bedrock：
- AWS_ROLE_TO_ASSUME
- AWS_REGION

使用上方的 AWS Bedrock 作業範例在執行時將 GitLab 作業權杖交換為臨時 AWS 憑證。

先決條件

在使用 Google Vertex AI 設定 Claude Code 之前，您需要：

具有以下條件的 Google Cloud 專案：
- 已啟用 Vertex AI API
- 設定為信任 GitLab OIDC 的 Workload Identity Federation
僅具有必要 Vertex AI 角色的專用服務帳戶
用於 WIF 的 GitLab CI/CD 變數：
- GCP_WORKLOAD_IDENTITY_PROVIDER（完整資源名稱）
- GCP_SERVICE_ACCOUNT（服務帳戶電子郵件）

設定說明

設定 Google Cloud 以允許 GitLab CI 作業透過 Workload Identity Federation 模擬服務帳戶。

必要設定：

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

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

GCP_WORKLOAD_IDENTITY_PROVIDER
GCP_SERVICE_ACCOUNT

在設定 → CI/CD → 變數中新增變數：

# 對於 Google Vertex AI：
- GCP_WORKLOAD_IDENTITY_PROVIDER
- GCP_SERVICE_ACCOUNT
- CLOUD_ML_REGION（例如，us-east5）

使用上方的 Google Vertex AI 作業範例在不儲存金鑰的情況下進行驗證。

設定範例

以下是您可以適應到管線的即用程式碼片段。

基本 .gitlab-ci.yml（Anthropic 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
    - npm install -g @anthropic-ai/claude-code
  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

AWS Bedrock 作業範例（OIDC）

先決條件：

已啟用 Amazon Bedrock，可存取您選擇的 Claude 模型
在 AWS 中設定 GitLab OIDC，具有信任您的 GitLab 專案和參考的角色
具有 Bedrock 權限的 IAM 角色（建議最小權限）

必要的 CI/CD 變數：

AWS_ROLE_TO_ASSUME：用於 Bedrock 存取的 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
    - npm install -g @anthropic-ai/claude-code
    # 將 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"

Bedrock 的模型 ID 包含區域特定的前綴和版本後綴（例如，us.anthropic.claude-3-7-sonnet-20250219-v1:0）。如果您的工作流程支援，請透過作業設定或提示傳遞所需的模型。

Google Vertex AI 作業範例（Workload Identity Federation）

先決條件：

在您的 GCP 專案中啟用 Vertex AI API
設定為信任 GitLab OIDC 的 Workload Identity Federation
具有 Vertex AI 權限的服務帳戶

必要的 CI/CD 變數：

GCP_WORKLOAD_IDENTITY_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 nodejs npm && apt-get clean
    - npm install -g @anthropic-ai/claude-code
    # 透過 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 專注且簡潔
提供清楚的 issue/MR 描述以減少迭代
設定合理的作業逾時以避免失控執行
在可能的情況下在 runner 中快取 npm 和套件安裝

CI 成本

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

GitLab Runner 時間：
- Claude 在您的 GitLab runner 上執行並消耗計算分鐘數
- 請參閱您的 GitLab 方案的 runner 計費詳情
API 成本：
- 每次 Claude 互動根據提示和回應大小消耗權杖
- 權杖使用量因任務複雜度和程式碼庫大小而異
- 請參閱 Anthropic 定價了解詳情
成本最佳化技巧：
- 使用特定的 @claude 指令以減少不必要的回合
- 設定適當的 max_turns 和作業逾時值
- 限制並發性以控制平行執行

安全性和治理

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

疑難排解

Claude 不回應 @claude 指令

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

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

確保 CI_JOB_TOKEN 對專案有足夠的權限，或使用具有 api 範圍的專案存取權杖
檢查 mcp__gitlab 工具在 --allowedTools 中已啟用
確認作業在 MR 的上下文中執行或透過 AI_FLOW_* 變數有足夠的上下文

驗證錯誤

對於 Anthropic API：確認 ANTHROPIC_API_KEY 有效且未過期
對於 Bedrock/Vertex：驗證 OIDC/WIF 設定、角色模擬和密鑰名稱；確認區域和模型可用性

進階設定

常見參數和變數

Claude Code 支援這些常用輸入：

prompt / prompt_file：內聯提供指令（-p）或透過檔案
max_turns：限制來回迭代的次數
timeout_minutes：限制總執行時間
ANTHROPIC_API_KEY：Anthropic API 所需（Bedrock/Vertex 不使用）
提供者特定環境：AWS_REGION，Vertex 的專案/區域變數

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

自訂 Claude 的行為

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

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

開始使用

使用 Claude Code 建構

Claude 程式碼 SDK

部署

管理

配置

參考資料

資源

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

​運作原理

​Claude 能做什麼？

​設定

​快速設定

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

​範例使用案例

​將 issue 轉換為 MR

​獲得實作協助

​快速修復錯誤

​使用 AWS Bedrock 和 Google Vertex AI

​先決條件

​設定說明

​先決條件

​設定說明

​先決條件

​設定說明

​設定範例

​基本 .gitlab-ci.yml（Anthropic API）

​AWS Bedrock 作業範例（OIDC）

​Google Vertex AI 作業範例（Workload Identity Federation）

​最佳實務

​CLAUDE.md 設定

​安全考量

​最佳化效能

​CI 成本

​安全性和治理

​疑難排解

​Claude 不回應 @claude 指令

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

​驗證錯誤

​進階設定

​常見參數和變數

​自訂 Claude 的行為

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

運作原理

Claude 能做什麼？

設定

快速設定

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

範例使用案例

將 issue 轉換為 MR

獲得實作協助

快速修復錯誤

使用 AWS Bedrock 和 Google Vertex AI

先決條件

設定說明

先決條件

設定說明

先決條件

設定說明

設定範例

基本 .gitlab-ci.yml（Anthropic API）

AWS Bedrock 作業範例（OIDC）

Google Vertex AI 作業範例（Workload Identity Federation）

最佳實務

CLAUDE.md 設定

安全考量

最佳化效能

CI 成本

安全性和治理

疑難排解

Claude 不回應 @claude 指令

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

驗證錯誤

進階設定

常見參數和變數

自訂 Claude 的行為