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 可以做什麼?
在 GitLab 管道中,Claude Code 可以:- 從議題描述或評論建立和更新 MR
- 分析效能迴歸並提出最佳化建議
- 直接在分支中實現功能,然後開啟 MR
- 修復由測試或評論識別的錯誤和迴歸
- 回應後續評論以反覆進行所要求的變更
設定
快速設定
開始使用的最快方式是在您的.gitlab-ci.yml 中新增一個最小化的工作,並將您的 API 金鑰設定為遮罩變數。
-
新增遮罩 CI/CD 變數
- 前往 Settings → CI/CD → Variables
- 新增
ANTHROPIC_API_KEY(遮罩,視需要保護)
-
在
.gitlab-ci.yml中新增 Claude 工作
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 設定工作負載身分識別聯盟 → GCP
- Claude API:建立並將
-
為 GitLab API 操作新增專案認證:
- 預設使用
CI_JOB_TOKEN,或建立具有api範圍的專案存取權杖 - 如果使用 PAT,將其儲存為
GITLAB_ACCESS_TOKEN(遮罩)
- 預設使用
-
在
.gitlab-ci.yml中新增 Claude 工作:使用 Claude API 的快速設定工作,或來自設定範例的提供者工作 -
(選用)啟用提及驅動的觸發:
- 為「評論(備註)」新增專案 webhook 至您的事件接聽程式(如果您使用的話)
- 當評論包含
@claude時,讓接聽程式使用AI_FLOW_INPUT和AI_FLOW_CONTEXT等變數呼叫管道觸發 API
使用案例範例
將議題轉換為 MR
在議題評論中:取得實作協助
在 MR 討論中:快速修復錯誤
在議題或 MR 評論中:搭配 Amazon Bedrock 和 Google Cloud 使用
針對企業環境,您可以在自己的雲端基礎設施上完全執行 Claude Code,並享有相同的開發者體驗。- Amazon Bedrock
- Google Cloud's Agent Platform
先決條件
在使用 Amazon Bedrock 設定 Claude Code 之前,您需要:- 一個 AWS 帳戶,具有 Amazon Bedrock 對所需 Claude 模型的存取權限
- 在 AWS IAM 中將 GitLab 設定為 OIDC 身分提供者
- 一個具有 Amazon Bedrock 權限的 IAM 角色,以及限制於您的 GitLab 專案/參考的信任政策
- 用於角色假設的 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)
先決條件:- Amazon Bedrock 已啟用,可存取您選擇的 Claude 模型
- GitLab OIDC 已在 AWS 中設定,具有信任您的 GitLab 專案和 refs 的角色
- 具有 Amazon Bedrock 權限的 IAM 角色(建議最小權限)
AWS_ROLE_TO_ASSUME:用於 Amazon Bedrock 存取的 IAM 角色 ARNAWS_REGION:Amazon Bedrock 區域(例如us-west-2)
id_tokens: 區塊鑄造工作的 OIDC 令牌,並將其公開為 GITLAB_OIDC_TOKEN。將 aud 設定為您在 AWS 的 IAM OIDC 身分提供者上設定的對象值,例如您的 GitLab 執行個體 URL。
Amazon Bedrock 的模型 ID 包含區域特定的前綴(例如
us.anthropic.claude-sonnet-4-6)。如果您的工作流程支援,請透過您的工作設定或提示傳遞所需的模型。Agent Platform 工作範例(工作負載身分聯盟)
先決條件:- Google Cloud 的 Agent Platform API 已在您的 GCP 專案中啟用
- 工作負載身分聯盟已設定為信任 GitLab OIDC
- 具有 Google Cloud Agent Platform 權限的服務帳戶
GCP_WORKLOAD_IDENTITY_PROVIDER:提供者資源名稱,不含//iam.googleapis.com/前綴,例如projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-providerGCP_SERVICE_ACCOUNT:服務帳戶電子郵件GCP_PROJECT_ID:Google Cloud 專案 IDCLOUD_ML_REGION:Google Cloud Agent Platform 區域(例如us-east5)
id_tokens: 區塊鑄造工作的 OIDC 令牌,並將其公開為 GITLAB_OIDC_TOKEN。將 aud 設定為您在工作負載身分池提供者上設定的對象值,例如您的 GitLab 執行個體 URL。工作將令牌寫入檔案,認證設定的 credential_source 項目告訴 Google 的驗證程式庫從該處讀取它。將 GOOGLE_APPLICATION_CREDENTIALS 設定為認證設定檔案使其可透過應用程式預設認證供 Claude Code 使用。
使用工作負載身分聯盟,您不需要儲存服務帳戶金鑰。使用存放庫特定的信任條件和最小權限服務帳戶。
最佳實踐
CLAUDE.md 設定
在儲存庫根目錄建立CLAUDE.md 檔案,以定義編碼標準、審查條件和專案特定規則。Claude 在執行期間會讀取此檔案,並在提出變更時遵循您的慣例。
安全考量
絕不將 API 金鑰或雲端認證提交到您的儲存庫。請務必使用 GitLab CI/CD 變數:- 將
ANTHROPIC_API_KEY新增為遮罩變數(如需要可保護它) - 盡可能使用提供者特定的 OIDC(無長期金鑰)
- 限制工作權限和網路出口
- 像審查任何其他貢獻者一樣審查 Claude 的 MR
最佳化效能
- 保持
CLAUDE.md專注且簡潔 - 提供清晰的議題/MR 描述以減少迭代
- 在執行器中盡可能快取 npm 和套件安裝
CI 成本
使用 Claude Code 搭配 GitLab CI/CD 時,請注意相關成本:-
GitLab Runner 時間:
- Claude 在您的 GitLab 執行器上執行,並消耗計算分鐘數
- 請參閱您的 GitLab 方案的執行器計費詳細資訊
-
API 成本:
- 每次 Claude 互動根據提示和回應大小消耗權杖
- 權杖使用量因任務複雜性和程式碼庫大小而異
- 詳細資訊請參閱 Anthropic 定價
-
成本最佳化提示:
- 使用特定的
@claude命令以減少不必要的回合 - 設定適當的
--max-turns和工作timeout值 - 限制並行以控制平行執行
- 使用特定的
疑難排解
Claude 未回應 @claude 指令
- 驗證您的管道是否被觸發(手動、MR 事件或透過筆記事件監聽器/webhook)
- 確保您的
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 設定、角色模擬和密碼名稱;確認區域和模型可用性
進階設定
常見參數和變數
使用這些 CLI 旗標、GitLab 關鍵字和變數來控制您工作中的 Claude Code 執行:-p:提供內聯指示,例如claude -p "Review this MR"--max-turns:限制往返迭代的次數timeout:使用 GitLab 的工作層級timeout關鍵字限制總工作執行時間,例如timeout: 30mANTHROPIC_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 在執行期間讀取此檔案並遵循您的規則。
- 自訂提示:透過工作中的
-p傳遞特定任務的指示。為不同的工作使用不同的提示(例如,審查、實作、重構)。