@claude,Claude 就可以分析您的程式碼、建立 pull request、實現功能和修復錯誤 - 同時遵循您專案的標準。如需在每個 PR 上自動發佈評論而無需觸發,請參閱 GitHub Code Review。
Claude Code GitHub Actions 建立在 Claude Agent SDK 之上,該 SDK 可實現 Claude Code 與您的應用程式的程式化整合。您可以使用 SDK 來建立超越 GitHub Actions 的自訂自動化工作流程。
為什麼使用 Claude Code GitHub Actions?
- 即時 PR 建立:描述您需要的內容,Claude 會建立包含所有必要變更的完整 PR
- 自動化程式碼實現:使用單一命令將議題轉換為可運作的程式碼
- 遵循您的標準:Claude 尊重您的
CLAUDE.md指南和現有程式碼模式 - 簡單設定:使用我們的安裝程式和 API 金鑰在幾分鐘內開始使用
- 預設安全:您的程式碼保留在 Github 的執行器上
Claude 可以做什麼?
Claude Code 提供了一個強大的 GitHub Action,改變了您使用程式碼的方式:Claude Code Action
此 GitHub Action 允許您在 GitHub Actions 工作流程中執行 Claude Code。您可以使用此功能在 Claude Code 之上建立任何自訂工作流程。 檢視儲存庫 →設定
快速設定
在 Claude Code 終端機中執行/install-github-app 以互動方式設定整合。此命令會在您的儲存庫上安裝 Claude GitHub App,然後引導您完成新增 GitHub Actions 工作流程和 API 金鑰密鑰的步驟。
安裝 GitHub App 後,命令會詢問是否繼續進行 GitHub Actions 設定。在 Claude Code v2.1.187 及更新版本中,您可以選擇暫時跳過以僅安裝 App 並停止,然後透過再次執行 /install-github-app 返回工作流程和密鑰步驟。較早的版本會直接進行工作流程選擇。
- 您必須是儲存庫管理員才能安裝 GitHub app 並新增密鑰
- GitHub app 將要求對內容、議題和 Pull request 的讀取和寫入權限
- 此快速入門方法僅適用於直接 Claude API 使用者。如果您使用 Amazon Bedrock 或 Google Cloud 的 Agent Platform,請參閱 使用 Amazon Bedrock 和 Google Cloud 部分。
手動設定
如果/install-github-app 命令失敗或您偏好手動設定,請遵循以下手動設定說明:
-
安裝 Claude GitHub app 到您的儲存庫:https://github.com/apps/claude
Claude GitHub app 需要以下儲存庫權限:
- Contents:讀取和寫入(修改儲存庫檔案)
- Issues:讀取和寫入(回應議題)
- Pull requests:讀取和寫入(建立 PR 和推送變更)
- 新增 ANTHROPIC_API_KEY 到您的儲存庫密鑰(了解如何在 GitHub Actions 中使用密鑰)
-
複製工作流程檔案 從 examples/claude.yml 到您的儲存庫的
.github/workflows/
從 Beta 升級
如果您目前使用 Claude Code GitHub Actions 的 beta 版本,我們建議您更新工作流程以使用 GA 版本。新版本簡化了設定,同時新增了強大的新功能,如自動模式偵測。基本變更
所有 beta 使用者必須對其工作流程檔案進行這些變更才能升級:- 更新 action 版本:將
@beta變更為@v1 - 移除模式設定:刪除
mode: "tag"或mode: "agent"(現在自動偵測) - 更新提示輸入:將
direct_prompt替換為prompt - 移動 CLI 選項:將
max_turns、model、custom_instructions等轉換為claude_args
重大變更參考
前後範例
Beta 版本:範例使用案例
Claude Code GitHub Actions 可以幫助您完成各種任務。examples 目錄包含適用於不同情境的現成工作流程。基本工作流程
使用 skills
prompt 輸入接受 skill 調用以及純文本:
- 對於存放在您的儲存庫
.claude/skills/目錄中的 skill,請在操作步驟之前執行actions/checkout,並傳遞/skill-name。 - 對於打包在外掛程式中的 skill,請使用
plugin_marketplaces和plugins輸入安裝外掛程式,並傳遞命名空間/plugin-name:skill-name。
code-review 外掛程式,並在每個新的或更新的提取請求上執行其 skill:
使用提示的自訂自動化
常見使用案例
在議題或 PR 評論中:最佳實踐
CLAUDE.md 設定
在您的儲存庫根目錄建立CLAUDE.md 檔案,以定義程式碼風格指南、審查標準、專案特定規則和偏好的模式。此檔案指導 Claude 對您的專案標準的理解。
安全考量
如需包括權限、身份驗證和最佳實踐的全面安全指導,請參閱 Claude Code Action 安全性文件。 始終使用 GitHub Secrets 來存放 API 金鑰:- 將您的 API 金鑰新增為名為
ANTHROPIC_API_KEY的儲存庫密鑰 - 在工作流程中參考它:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} - 將 action 權限限制為僅必要的權限
- 在合併前審查 Claude 的建議
${{ secrets.ANTHROPIC_API_KEY }})而不是直接在工作流程檔案中硬編碼 API 金鑰。
最佳化效能
使用議題範本提供上下文,保持您的CLAUDE.md 簡潔且專注,並為您的工作流程設定適當的逾時。
CI 成本
使用 Claude Code GitHub Actions 時,請注意相關成本: GitHub Actions 成本:- Claude Code 在 GitHub 託管的執行器上執行,這會消耗您的 GitHub Actions 分鐘數
- 請參閱 GitHub 的計費文件以了解詳細的定價和分鐘限制
- 每次 Claude 互動都會根據提示和回應的長度消耗 API 令牌
- 令牌使用量因任務複雜性和程式碼庫大小而異
- 請參閱 Claude 的定價頁面以了解目前的令牌費率
- 使用特定的
@claude命令來減少不必要的 API 呼叫 - 在
claude_args中設定適當的--max-turns以防止過度迭代 - 設定工作流程級別的逾時以避免失控的工作
- 考慮使用 GitHub 的並行控制來限制平行執行
設定範例
Claude Code Action v1 使用統一參數簡化了設定:- 統一提示介面 - 對所有指令使用
prompt - Skills - 直接從提示中呼叫已安裝的 skills
- CLI 傳遞 - 透過
claude_args的任何 Claude Code CLI 引數 - 靈活的觸發器 - 適用於任何 GitHub 事件
使用 Amazon Bedrock 和 Google Cloud
對於企業環境,您可以使用 Claude Code GitHub Actions 搭配您自己的雲端基礎設施。此方法讓您可以控制資料駐留和計費,同時保持相同的功能。先決條件
在使用雲端提供者設定 Claude Code GitHub Actions 之前,您需要:對於 Google Cloud 的 Agent Platform:
- 啟用了 Google Cloud 的 Agent Platform 的 Google Cloud 專案
- 為 GitHub Actions 設定的工作負載身份聯盟
- 具有所需權限的服務帳戶
- GitHub App(建議)或使用預設 GITHUB_TOKEN
對於 Amazon Bedrock:
- 啟用了 Amazon Bedrock 的 AWS 帳戶
- 在 AWS 中設定的 GitHub OIDC 身份提供者
- 具有 Amazon Bedrock 權限的 IAM 角色
- GitHub App(建議)或使用預設 GITHUB_TOKEN
1
建立自訂 GitHub App(建議用於第三方提供者)
為了在使用 Google Cloud 的 Agent Platform 或 Amazon Bedrock 等第三方提供者時獲得最佳控制和安全性,我們建議建立您自己的 GitHub App:Claude API 的替代方案或如果您不想設定自己的 Github app:使用官方 Anthropic app:
- 前往 https://github.com/settings/apps/new
- 填寫基本資訊:
- GitHub App 名稱:選擇唯一的名稱(例如’YourOrg Claude Assistant’)
- 首頁 URL:您的組織網站或儲存庫 URL
- 設定 app 設定:
- Webhooks:取消勾選’Active’(此整合不需要)
- 設定所需的權限:
- 儲存庫權限:
- Contents:讀取和寫入
- Issues:讀取和寫入
- Pull requests:讀取和寫入
- 儲存庫權限:
- 點擊’Create GitHub App’
- 建立後,點擊’Generate a private key’並儲存下載的
.pem檔案 - 從 app 設定頁面記下您的 App ID
- 將 app 安裝到您的儲存庫:
- 從您的 app 設定頁面,點擊左側邊欄中的’Install App’
- 選擇您的帳戶或組織
- 選擇’Only select repositories’並選擇特定儲存庫
- 點擊’Install’
- 將私鑰新增為儲存庫密鑰:
- 前往您的儲存庫的 Settings → Secrets and variables → Actions
- 建立名為
APP_PRIVATE_KEY的新密鑰,內容為.pem檔案的內容
- 將 App ID 新增為密鑰:
- 建立名為
APP_ID的新密鑰,內容為您的 GitHub App 的 ID
此 app 將與 actions/create-github-app-token action 一起使用,以在您的工作流程中產生身份驗證令牌。
- 從以下位置安裝:https://github.com/apps/claude
- 無需額外的身份驗證設定
2
設定雲端提供者身份驗證
選擇您的雲端提供者並設定安全的身份驗證:
Amazon Bedrock
Amazon Bedrock
設定 AWS 以允許 GitHub Actions 安全地進行身份驗證,而無需儲存認證。
安全性注意:使用儲存庫特定的設定並僅授予最少所需的權限。必需的設定:
-
啟用 Amazon Bedrock:
- 請求在 Amazon Bedrock 中存取 Claude 模型
- 對於跨區域模型,請在所有必需的區域中請求存取
-
設定 GitHub OIDC 身份提供者:
- 提供者 URL:
https://token.actions.githubusercontent.com - 受眾:
sts.amazonaws.com
- 提供者 URL:
-
為 GitHub Actions 建立 IAM 角色:
- 受信任的實體類型:Web 身份
- 身份提供者:
token.actions.githubusercontent.com - 權限:
AmazonBedrockFullAccess政策 - 為您的特定儲存庫設定信任政策
- AWS_ROLE_TO_ASSUME:您建立的 IAM 角色的 ARN
Google Cloud 的 Agent Platform
Google Cloud 的 Agent Platform
設定 Google Cloud 以允許 GitHub Actions 安全地進行身份驗證,而無需儲存認證。
安全性注意:使用儲存庫特定的設定並僅授予最少所需的權限。必需的設定:
-
在您的 Google Cloud 專案中啟用 API:
- IAM Credentials API
- Security Token Service (STS) API
- Google Cloud 的 Agent Platform API
-
建立工作負載身份聯盟資源:
- 建立工作負載身份池
- 新增 GitHub OIDC 提供者,具有:
- 簽發者:
https://token.actions.githubusercontent.com - 儲存庫和擁有者的屬性對應
- 安全性建議:使用儲存庫特定的屬性條件
- 簽發者:
-
建立服務帳戶:
- 僅授予
Vertex AI User角色 - 安全性建議:為每個儲存庫建立專用服務帳戶
- 僅授予
-
設定 IAM 繫結:
- 允許工作負載身份池模擬服務帳戶
- 安全性建議:使用儲存庫特定的主體集
- GCP_WORKLOAD_IDENTITY_PROVIDER:完整的提供者資源名稱
- GCP_SERVICE_ACCOUNT:服務帳戶電子郵件地址
3
新增必需的密鑰
將以下密鑰新增到您的儲存庫(Settings → Secrets and variables → Actions):
對於 Claude API(直接):
-
對於 API 身份驗證:
ANTHROPIC_API_KEY:您的 Claude API 金鑰,來自 console.anthropic.com
-
對於 GitHub App(如果使用您自己的 app):
APP_ID:您的 GitHub App 的 IDAPP_PRIVATE_KEY:私鑰 (.pem) 內容
對於 Google Cloud 的 Agent Platform
-
對於 GCP 身份驗證:
GCP_WORKLOAD_IDENTITY_PROVIDERGCP_SERVICE_ACCOUNT
-
對於 GitHub App(如果使用您自己的 app):
APP_ID:您的 GitHub App 的 IDAPP_PRIVATE_KEY:私鑰 (.pem) 內容
對於 Amazon Bedrock
-
對於 AWS 身份驗證:
AWS_ROLE_TO_ASSUME
-
對於 GitHub App(如果使用您自己的 app):
APP_ID:您的 GitHub App 的 IDAPP_PRIVATE_KEY:私鑰 (.pem) 內容
4
建立工作流程檔案
建立與您的雲端提供者整合的 GitHub Actions 工作流程檔案。以下範例顯示了 Amazon Bedrock 和 Google Cloud 的 Agent Platform 的完整設定:
Amazon Bedrock 工作流程
Amazon Bedrock 工作流程
先決條件:
- 啟用了 Amazon Bedrock 存取且具有 Claude 模型權限
- GitHub 在 AWS 中設定為 OIDC 身份提供者
- 具有 Amazon Bedrock 權限且信任 GitHub Actions 的 IAM 角色
Google Cloud 的 Agent Platform 工作流程
Google Cloud 的 Agent Platform 工作流程
先決條件:
- 在您的 GCP 專案中啟用了 Google Cloud 的 Agent Platform API
- 為 GitHub 設定的工作負載身份聯盟
- 具有 Google Cloud 的 Agent Platform 權限的服務帳戶
故障排除
Claude 不回應 @claude 命令
驗證 GitHub App 是否正確安裝,檢查工作流程是否已啟用,確保 API 金鑰已在儲存庫密鑰中設定,並確認評論包含@claude(不是 /claude)。
CI 不在 Claude 的提交上執行
確保您使用的是 GitHub App 或自訂 app(不是 Actions 使用者),檢查工作流程觸發器是否包括必要的事件,並驗證 app 權限是否包括 CI 觸發器。身份驗證錯誤
確認 API 金鑰有效且具有足夠的權限。對於 Amazon Bedrock 或 Google Cloud 的 Agent Platform,檢查認證設定並確保密鑰在工作流程中命名正確。進階設定
Action 參數
Claude Code Action v1 使用簡化的設定:
*提示是可選的 - 當在議題/PR 評論中省略時,Claude 回應觸發短語
**對於直接 Claude API 是必需的,對於 Amazon Bedrock 或 Google Cloud 的 Agent Platform 不是必需的
傳遞 CLI 引數
claude_args 參數接受任何 Claude Code CLI 引數:
--max-turns:最大對話輪數(預設:10)--model:要使用的模型(例如claude-sonnet-5)--mcp-config:MCP 設定的路徑--allowedTools:允許的工具的逗號分隔清單。--allowed-tools別名也可以使用。--debug:啟用偵錯輸出
替代整合方法
雖然/install-github-app 命令是推薦的方法,但您也可以:
- 自訂 GitHub App:對於需要品牌使用者名稱或自訂身份驗證流程的組織。建立您自己的 GitHub App,具有所需的權限(contents、issues、pull requests),並使用 actions/create-github-app-token action 在您的工作流程中產生令牌。
- 手動 GitHub Actions:直接工作流程設定以獲得最大靈活性
- MCP 設定:Model Context Protocol 伺服器的動態載入
自訂 Claude 的行為
您可以透過兩種方式自訂 Claude 的行為:- CLAUDE.md:在您的儲存庫根目錄中的
CLAUDE.md檔案中定義編碼標準、審查標準和專案特定規則。Claude 在建立 PR 和回應請求時將遵循這些指南。請查看我們的 Memory 文件以取得更多詳細資訊。 - 自訂提示:在工作流程檔案中使用
prompt參數來提供工作流程特定的指令。這允許您為不同的工作流程或任務自訂 Claude 的行為。