Skip to main content
Claude Code GitHub Actions 為您的 GitHub 工作流程帶來 AI 驅動的自動化。只需在任何 PR 或議題中提及 @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 命令失敗或您偏好手動設定,請遵循以下手動設定說明:
  1. 安裝 Claude GitHub app 到您的儲存庫:https://github.com/apps/claude Claude GitHub app 需要以下儲存庫權限:
    • Contents:讀取和寫入(修改儲存庫檔案)
    • Issues:讀取和寫入(回應議題)
    • Pull requests:讀取和寫入(建立 PR 和推送變更)
    如需有關安全性和權限的更多詳細資訊,請參閱 安全性文件
  2. 新增 ANTHROPIC_API_KEY 到您的儲存庫密鑰(了解如何在 GitHub Actions 中使用密鑰
  3. 複製工作流程檔案examples/claude.yml 到您的儲存庫的 .github/workflows/
完成快速入門或手動設定後,透過在議題或 PR 評論中標記 @claude 來測試 action。

從 Beta 升級

Claude Code GitHub Actions v1.0 引入了重大變更,需要更新您的工作流程檔案才能從 beta 版本升級到 v1.0。
如果您目前使用 Claude Code GitHub Actions 的 beta 版本,我們建議您更新工作流程以使用 GA 版本。新版本簡化了設定,同時新增了強大的新功能,如自動模式偵測。

基本變更

所有 beta 使用者必須對其工作流程檔案進行這些變更才能升級:
  1. 更新 action 版本:將 @beta 變更為 @v1
  2. 移除模式設定:刪除 mode: "tag"mode: "agent"(現在自動偵測)
  3. 更新提示輸入:將 direct_prompt 替換為 prompt
  4. 移動 CLI 選項:將 max_turnsmodelcustom_instructions 等轉換為 claude_args

重大變更參考

前後範例

Beta 版本:
GA 版本 (v1.0):
該 action 現在會根據您的設定自動偵測是否在互動模式(回應 @claude 提及)或自動化模式(立即使用提示執行)中執行。

範例使用案例

Claude Code GitHub Actions 可以幫助您完成各種任務。examples 目錄包含適用於不同情境的現成工作流程。

基本工作流程

使用 skills

prompt 輸入接受 skill 調用以及純文本:
  • 對於存放在您的儲存庫 .claude/skills/ 目錄中的 skill,請在操作步驟之前執行 actions/checkout,並傳遞 /skill-name
  • 對於打包在外掛程式中的 skill,請使用 plugin_marketplacesplugins 輸入安裝外掛程式,並傳遞命名空間 /plugin-name:skill-name
以下工作流程安裝 code-review 外掛程式,並在每個新的或更新的提取請求上執行其 skill:

使用提示的自訂自動化

常見使用案例

在議題或 PR 評論中:
Claude 將自動分析上下文並做出適當的回應。

最佳實踐

CLAUDE.md 設定

在您的儲存庫根目錄建立 CLAUDE.md 檔案,以定義程式碼風格指南、審查標準、專案特定規則和偏好的模式。此檔案指導 Claude 對您的專案標準的理解。

安全考量

永遠不要直接將 API 金鑰提交到您的儲存庫。
如需包括權限、身份驗證和最佳實踐的全面安全指導,請參閱 Claude Code Action 安全性文件 始終使用 GitHub Secrets 來存放 API 金鑰:
  • 將您的 API 金鑰新增為名為 ANTHROPIC_API_KEY 的儲存庫密鑰
  • 在工作流程中參考它:anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
  • 將 action 權限限制為僅必要的權限
  • 在合併前審查 Claude 的建議
始終使用 GitHub Secrets(例如 ${{ secrets.ANTHROPIC_API_KEY }})而不是直接在工作流程檔案中硬編碼 API 金鑰。

最佳化效能

使用議題範本提供上下文,保持您的 CLAUDE.md 簡潔且專注,並為您的工作流程設定適當的逾時。

CI 成本

使用 Claude Code GitHub Actions 時,請注意相關成本: GitHub Actions 成本:
  • Claude Code 在 GitHub 託管的執行器上執行,這會消耗您的 GitHub Actions 分鐘數
  • 請參閱 GitHub 的計費文件以了解詳細的定價和分鐘限制
API 成本:
  • 每次 Claude 互動都會根據提示和回應的長度消耗 API 令牌
  • 令牌使用量因任務複雜性和程式碼庫大小而異
  • 請參閱 Claude 的定價頁面以了解目前的令牌費率
成本最佳化提示:
  • 使用特定的 @claude 命令來減少不必要的 API 呼叫
  • claude_args 中設定適當的 --max-turns 以防止過度迭代
  • 設定工作流程級別的逾時以避免失控的工作
  • 考慮使用 GitHub 的並行控制來限制平行執行

設定範例

Claude Code Action v1 使用統一參數簡化了設定:
主要功能:
  • 統一提示介面 - 對所有指令使用 prompt
  • Skills - 直接從提示中呼叫已安裝的 skills
  • CLI 傳遞 - 透過 claude_args 的任何 Claude Code CLI 引數
  • 靈活的觸發器 - 適用於任何 GitHub 事件
訪問 examples 目錄以取得完整的工作流程檔案。
當回應議題或 PR 評論時,Claude 會自動回應 @claude 提及。對於其他事件,使用 prompt 參數來提供指令。

使用 Amazon Bedrock 和 Google Cloud

對於企業環境,您可以使用 Claude Code GitHub Actions 搭配您自己的雲端基礎設施。此方法讓您可以控制資料駐留和計費,同時保持相同的功能。

先決條件

在使用雲端提供者設定 Claude Code GitHub Actions 之前,您需要:

對於 Google Cloud 的 Agent Platform:

  1. 啟用了 Google Cloud 的 Agent Platform 的 Google Cloud 專案
  2. 為 GitHub Actions 設定的工作負載身份聯盟
  3. 具有所需權限的服務帳戶
  4. GitHub App(建議)或使用預設 GITHUB_TOKEN

對於 Amazon Bedrock:

  1. 啟用了 Amazon Bedrock 的 AWS 帳戶
  2. 在 AWS 中設定的 GitHub OIDC 身份提供者
  3. 具有 Amazon Bedrock 權限的 IAM 角色
  4. GitHub App(建議)或使用預設 GITHUB_TOKEN
1

建立自訂 GitHub App(建議用於第三方提供者)

為了在使用 Google Cloud 的 Agent Platform 或 Amazon Bedrock 等第三方提供者時獲得最佳控制和安全性,我們建議建立您自己的 GitHub App:
  1. 前往 https://github.com/settings/apps/new
  2. 填寫基本資訊:
    • GitHub App 名稱:選擇唯一的名稱(例如’YourOrg Claude Assistant’)
    • 首頁 URL:您的組織網站或儲存庫 URL
  3. 設定 app 設定:
    • Webhooks:取消勾選’Active’(此整合不需要)
  4. 設定所需的權限:
    • 儲存庫權限
      • Contents:讀取和寫入
      • Issues:讀取和寫入
      • Pull requests:讀取和寫入
  5. 點擊’Create GitHub App’
  6. 建立後,點擊’Generate a private key’並儲存下載的 .pem 檔案
  7. 從 app 設定頁面記下您的 App ID
  8. 將 app 安裝到您的儲存庫:
    • 從您的 app 設定頁面,點擊左側邊欄中的’Install App’
    • 選擇您的帳戶或組織
    • 選擇’Only select repositories’並選擇特定儲存庫
    • 點擊’Install’
  9. 將私鑰新增為儲存庫密鑰:
    • 前往您的儲存庫的 Settings → Secrets and variables → Actions
    • 建立名為 APP_PRIVATE_KEY 的新密鑰,內容為 .pem 檔案的內容
  10. 將 App ID 新增為密鑰:
  • 建立名為 APP_ID 的新密鑰,內容為您的 GitHub App 的 ID
此 app 將與 actions/create-github-app-token action 一起使用,以在您的工作流程中產生身份驗證令牌。
Claude API 的替代方案或如果您不想設定自己的 Github app:使用官方 Anthropic app:
  1. 從以下位置安裝:https://github.com/apps/claude
  2. 無需額外的身份驗證設定
2

設定雲端提供者身份驗證

選擇您的雲端提供者並設定安全的身份驗證:
設定 AWS 以允許 GitHub Actions 安全地進行身份驗證,而無需儲存認證。
安全性注意:使用儲存庫特定的設定並僅授予最少所需的權限。
必需的設定
  1. 啟用 Amazon Bedrock
    • 請求在 Amazon Bedrock 中存取 Claude 模型
    • 對於跨區域模型,請在所有必需的區域中請求存取
  2. 設定 GitHub OIDC 身份提供者
    • 提供者 URL:https://token.actions.githubusercontent.com
    • 受眾:sts.amazonaws.com
  3. 為 GitHub Actions 建立 IAM 角色
    • 受信任的實體類型:Web 身份
    • 身份提供者:token.actions.githubusercontent.com
    • 權限:AmazonBedrockFullAccess 政策
    • 為您的特定儲存庫設定信任政策
必需的值設定後,您將需要:
  • AWS_ROLE_TO_ASSUME:您建立的 IAM 角色的 ARN
OIDC 比使用靜態 AWS 存取金鑰更安全,因為認證是臨時的並自動輪換。
請參閱 AWS 文件以取得詳細的 OIDC 設定說明。
設定 Google Cloud 以允許 GitHub Actions 安全地進行身份驗證,而無需儲存認證。
安全性注意:使用儲存庫特定的設定並僅授予最少所需的權限。
必需的設定
  1. 在您的 Google Cloud 專案中啟用 API
    • IAM Credentials API
    • Security Token Service (STS) API
    • Google Cloud 的 Agent Platform API
  2. 建立工作負載身份聯盟資源
    • 建立工作負載身份池
    • 新增 GitHub OIDC 提供者,具有:
      • 簽發者:https://token.actions.githubusercontent.com
      • 儲存庫和擁有者的屬性對應
      • 安全性建議:使用儲存庫特定的屬性條件
  3. 建立服務帳戶
    • 僅授予 Vertex AI User 角色
    • 安全性建議:為每個儲存庫建立專用服務帳戶
  4. 設定 IAM 繫結
    • 允許工作負載身份池模擬服務帳戶
    • 安全性建議:使用儲存庫特定的主體集
必需的值設定後,您將需要:
  • GCP_WORKLOAD_IDENTITY_PROVIDER:完整的提供者資源名稱
  • GCP_SERVICE_ACCOUNT:服務帳戶電子郵件地址
工作負載身份聯盟消除了對可下載服務帳戶金鑰的需求,提高了安全性。
如需詳細的設定說明,請參閱 Google Cloud 工作負載身份聯盟文件
3

新增必需的密鑰

將以下密鑰新增到您的儲存庫(Settings → Secrets and variables → Actions):

對於 Claude API(直接):

  1. 對於 API 身份驗證
  2. 對於 GitHub App(如果使用您自己的 app)
    • APP_ID:您的 GitHub App 的 ID
    • APP_PRIVATE_KEY:私鑰 (.pem) 內容

對於 Google Cloud 的 Agent Platform

  1. 對於 GCP 身份驗證
    • GCP_WORKLOAD_IDENTITY_PROVIDER
    • GCP_SERVICE_ACCOUNT
  2. 對於 GitHub App(如果使用您自己的 app)
    • APP_ID:您的 GitHub App 的 ID
    • APP_PRIVATE_KEY:私鑰 (.pem) 內容

對於 Amazon Bedrock

  1. 對於 AWS 身份驗證
    • AWS_ROLE_TO_ASSUME
  2. 對於 GitHub App(如果使用您自己的 app)
    • APP_ID:您的 GitHub App 的 ID
    • APP_PRIVATE_KEY:私鑰 (.pem) 內容
4

建立工作流程檔案

建立與您的雲端提供者整合的 GitHub Actions 工作流程檔案。以下範例顯示了 Amazon Bedrock 和 Google Cloud 的 Agent Platform 的完整設定:
先決條件:
  • 啟用了 Amazon Bedrock 存取且具有 Claude 模型權限
  • GitHub 在 AWS 中設定為 OIDC 身份提供者
  • 具有 Amazon Bedrock 權限且信任 GitHub Actions 的 IAM 角色
必需的 GitHub 密鑰:
Amazon Bedrock 的模型 ID 格式包括區域前綴(例如 us.anthropic.claude-sonnet-4-6)。
先決條件:
  • 在您的 GCP 專案中啟用了 Google Cloud 的 Agent Platform API
  • 為 GitHub 設定的工作負載身份聯盟
  • 具有 Google Cloud 的 Agent Platform 權限的服務帳戶
必需的 GitHub 密鑰:
專案 ID 會自動從 Google Cloud 身份驗證步驟中擷取,因此您無需硬編碼它。

故障排除

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 Code Action 文件以取得有關身份驗證、安全性和進階設定的詳細指南。

自訂 Claude 的行為

您可以透過兩種方式自訂 Claude 的行為:
  1. CLAUDE.md:在您的儲存庫根目錄中的 CLAUDE.md 檔案中定義編碼標準、審查標準和專案特定規則。Claude 在建立 PR 和回應請求時將遵循這些指南。請查看我們的 Memory 文件以取得更多詳細資訊。
  2. 自訂提示:在工作流程檔案中使用 prompt 參數來提供工作流程特定的指令。這允許您為不同的工作流程或任務自訂 Claude 的行為。
Claude 在建立 PR 和回應請求時將遵循這些指南。