Claude Code GitHub Actions

了解如何將 Claude Code 整合到您的開發工作流程中，使用 Claude Code GitHub Actions

Claude Code GitHub Actions 為您的 GitHub 工作流程帶來 AI 驅動的自動化。只需在任何 PR 或議題中提及 @claude，Claude 就可以分析您的程式碼、建立 pull request、實現功能和修復錯誤 - 同時遵循您專案的標準。如需在每個 PR 上自動發佈評論而無需觸發，請參閱 GitHub Code Review。

為什麼使用 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 之上建立任何自訂工作流程。

檢視儲存庫 →

設定

快速設定

設定此 action 的最簡單方法是透過終端機中的 Claude Code。只需開啟 claude 並執行 /install-github-app。

此命令將引導您完成 GitHub app 和所需密鑰的設定。

手動設定

如果 /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/

從 Beta 升級

如果您目前使用 Claude Code GitHub Actions 的 beta 版本，我們建議您更新工作流程以使用 GA 版本。新版本簡化了設定，同時新增了強大的新功能，如自動模式偵測。

基本變更

所有 beta 使用者必須對其工作流程檔案進行這些變更才能升級：

1. 更新 action 版本：將 @beta 變更為 @v1
2. 移除模式設定：刪除 mode: "tag" 或 mode: "agent"（現在自動偵測）
3. 更新提示輸入：將 direct_prompt 替換為 prompt
4. 移動 CLI 選項：將 max_turns、model、custom_instructions 等轉換為 claude_args

重大變更參考

前後範例

Beta 版本：

- uses: anthropics/claude-code-action@beta
  with:
    mode: "tag"
    direct_prompt: "Review this PR for security issues"
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    custom_instructions: "Follow our coding standards"
    max_turns: "10"
    model: "claude-sonnet-4-6"

GA 版本 (v1.0)：

- uses: anthropics/claude-code-action@v1
  with:
    prompt: "Review this PR for security issues"
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    claude_args: |
      --append-system-prompt "Follow our coding standards"
      --max-turns 10
      --model claude-sonnet-4-6

範例使用案例

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

基本工作流程

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          # Responds to @claude mentions in comments

使用 skills

prompt 輸入接受 skill 調用以及純文本：

• 對於存放在您的儲存庫 .claude/skills/ 目錄中的 skill，請在操作步驟之前執行 actions/checkout，並傳遞 /skill-name。
• 對於打包在外掛程式中的 skill，請使用 plugin_marketplaces 和 plugins 輸入安裝外掛程式，並傳遞命名空間 /plugin-name:skill-name。

以下工作流程安裝 code-review 外掛程式，並在每個新的或更新的提取請求上執行其 skill：

name: Code Review
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          plugin_marketplaces: "https://github.com/anthropics/claude-code.git"
          plugins: "code-review@claude-code-plugins"
          prompt: "/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"

使用提示的自訂自動化

name: Daily Report
on:
  schedule:
    - cron: "0 9 * * *"
jobs:
  report:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "Generate a summary of yesterday's commits and open issues"
          claude_args: "--model opus"

常見使用案例

在議題或 PR 評論中：

@claude implement this feature based on the issue description
@claude how should I implement user authentication for this endpoint?
@claude fix the TypeError in the user dashboard component

Claude 將自動分析上下文並做出適當的回應。

最佳實踐

CLAUDE.md 設定

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

安全考量

如需包括權限、身份驗證和最佳實踐的全面安全指導，請參閱 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 使用統一參數簡化了設定：

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    prompt: "Your instructions here" # Optional
    claude_args: "--max-turns 5" # Optional CLI arguments

主要功能：

• 統一提示介面 - 對所有指令使用 prompt
• Skills - 直接從提示中呼叫已安裝的 skills
• CLI 傳遞 - 透過 claude_args 的任何 Claude Code CLI 引數
• 靈活的觸發器 - 適用於任何 GitHub 事件

訪問 examples 目錄以取得完整的工作流程檔案。

使用 Amazon Bedrock 和 Google Vertex AI

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

先決條件

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

對於 Google Cloud Vertex AI：

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

對於 Amazon Bedrock：

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

name: Claude PR Action

permissions:
contents: write
pull-requests: write
issues: write
id-token: write

on:
issue_comment:
types: [created]
pull_request_review_comment:
types: [created]
issues:
types: [opened, assigned]

jobs:
claude-pr:
if: |
(github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
(github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
(github.event_name == 'issues' && contains(github.event.issue.body, '@claude'))
runs-on: ubuntu-latest
env:
AWS_REGION: us-west-2
steps:
- name: Checkout repository
uses: actions/checkout@v4

- name: Generate GitHub App token
id: app-token
uses: actions/create-github-app-token@v2
with:
app-id: ${{ secrets.APP_ID }}
private-key: ${{ secrets.APP_PRIVATE_KEY }}

- name: Configure AWS Credentials (OIDC)
uses: aws-actions/configure-aws-credentials@v4
with:
role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}
aws-region: us-west-2

- uses: anthropics/claude-code-action@v1
with:
github_token: ${{ steps.app-token.outputs.token }}
use_bedrock: "true"
claude_args: '--model us.anthropic.claude-sonnet-4-6 --max-turns 10'

name: Claude PR Action

permissions:
contents: write
pull-requests: write
issues: write
id-token: write

on:
issue_comment:
types: [created]
pull_request_review_comment:
types: [created]
issues:
types: [opened, assigned]

jobs:
claude-pr:
if: |
(github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
(github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
(github.event_name == 'issues' && contains(github.event.issue.body, '@claude'))
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4

- name: Generate GitHub App token
id: app-token
uses: actions/create-github-app-token@v2
with:
app-id: ${{ secrets.APP_ID }}
private-key: ${{ secrets.APP_PRIVATE_KEY }}

- name: Authenticate to Google Cloud
id: auth
uses: google-github-actions/auth@v2
with:
workload_identity_provider: ${{ secrets.GCP_WORKLOAD_IDENTITY_PROVIDER }}
service_account: ${{ secrets.GCP_SERVICE_ACCOUNT }}

- uses: anthropics/claude-code-action@v1
with:
github_token: ${{ steps.app-token.outputs.token }}
trigger_phrase: "@claude"
use_vertex: "true"
claude_args: '--model claude-sonnet-4-5@20250929 --max-turns 10'
env:
ANTHROPIC_VERTEX_PROJECT_ID: ${{ steps.auth.outputs.project_id }}
CLOUD_ML_REGION: us-east5
VERTEX_REGION_CLAUDE_4_5_SONNET: us-east5

故障排除

Claude 不回應 @claude 命令

驗證 GitHub App 是否正確安裝，檢查工作流程是否已啟用，確保 API 金鑰已在儲存庫密鑰中設定，並確認評論包含 @claude（不是 /claude）。

CI 不在 Claude 的提交上執行

確保您使用的是 GitHub App 或自訂 app（不是 Actions 使用者），檢查工作流程觸發器是否包括必要的事件，並驗證 app 權限是否包括 CI 觸發器。

身份驗證錯誤

確認 API 金鑰有效且具有足夠的權限。對於 Bedrock/Vertex，檢查認證設定並確保密鑰在工作流程中命名正確。

進階設定

Action 參數

Claude Code Action v1 使用簡化的設定：

*提示是可選的 - 當在議題/PR 評論中省略時，Claude 回應觸發短語
**對於直接 Claude API 是必需的，對於 Bedrock/Vertex 不是必需的

傳遞 CLI 引數

claude_args 參數接受任何 Claude Code CLI 引數：

claude_args: "--max-turns 5 --model claude-sonnet-4-6 --mcp-config /path/to/config.json"

常見引數：

• --max-turns：最大對話輪數（預設：10）
• --model：要使用的模型（例如 claude-sonnet-4-6）
• --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 和回應請求時將遵循這些指南。