用法

Claude Code GitHub Actions 配置教程：在 Issue 和 PR 裡 @claude

釋出於 2026 年 10 月 30 日 · 最後核對 2026 年 10 月 30 日

Claude Code GitHub Actions 是一個在倉庫工作流裡執行 Claude Code 的 GitHub Action：在 PR 或 Issue 評論裡 @claude，Claude 就會分析程式碼、實現修改並推送提交。這一頁是配置步驟：快速安裝和手動安裝各怎麼做、基本工作流怎麼寫、常用引數、誰能觸發、費用和安全注意事項，以及不響應時看什麼。內容按 Anthropic 的 Claude Code GitHub Actions 中文整理，2026 年 10 月 30 日對照原文核對。

它能做什麼

Claude Code GitHub Action 在倉庫的工作流裡執行 Claude Code。在 PR 或 Issue 評論裡提及 @claude，Claude 會分析程式碼、實現修改並推送提交。你也可以給它一個 prompt，讓它在任意 GitHub 事件上自動執行。官方文件列出的用途有：把 Issue 變成 PR、根據評論修 bug、自動化重複任務。

幾個產品都叫 Claude Code。本頁講的是用倉庫裡的工作流檔案配置的 claude-code-action。如果你只想要每個 PR 都自動審查而不寫工作流，官方文件指向的是另一個產品 Code Review。

配置：快速安裝和手動安裝

兩種方式都需要倉庫的管理員權限。

快速安裝

/install-github-app 只支援 github.com 倉庫。如果倉庫的 git remote 在 gitlab.com 或 bitbucket.org，命令會列印提示並退出，不會開始安裝。

1. 安裝 GitHub CLI，並用 gh auth login 登入。Claude Code 會檢查它，缺失時給出警告。
2. 在要連線的倉庫裡開啟 claude，執行 /install-github-app，按提示操作。Claude Code 先安裝 Claude GitHub App，再為工作流設定認證金鑰。
3. 認證金鑰的選擇：如果 Claude Code 已經有 API key，會直接複用，並且在倉庫裡已有 ANTHROPIC_API_KEY 金鑰時詢問是否保留；否則在“用你的 Claude 訂閱建立長期令牌”和“貼上 API key”之間二選一。
4. Claude Code 把憑據存成倉庫金鑰：API key 對應 ANTHROPIC_API_KEY，訂閱令牌對應 CLAUDE_CODE_OAUTH_TOKEN。
5. Claude Code 推送一個帶有你所選工作流檔案的分支，檔案已經設為使用這個金鑰，並在瀏覽器裡開啟 GitHub，PR 已經準備好。建立併合並這個 PR，倉庫裡就可以用 @claude 了。

想中途停止，按 Esc：正在進行的步驟會做完，之後的步驟不再開始，結束時的訊息會列出倉庫裡已經發生的事，比如已推送的分支或已儲存的金鑰。安裝 GitHub App 之後，Claude Code 會問是否繼續 GitHub Actions 的設定；選 Skip for now 就只裝 App，之後再執行 /install-github-app 完成工作流和金鑰兩步。

如果你選了審查工作流，Claude 會把每條審查發在 PR 本身：發現的每個問題發一條行內評論，沒發現問題就發一條彙總評論。Claude 會跳過一些 PR，比如草稿。v2.1.229 之前，Claude 只把審查寫進工作流執行日誌。

要更新早期版本生成的審查工作流，二選一：

• 再次執行 /install-github-app。倉庫裡已有 claude.yml 時，選 Update workflow file with latest version。Claude Code 把新的工作流檔案推到一個新分支並開 PR，和第一次安裝一樣。
• 自己把下文審查工作流示例裡的 --comment 引數和 claude_args 那一行加進已提交的檔案，這樣能保留你對檔案做過的其他修改。

如果你用的是 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry，官方文件把你指向另一頁：Use Claude Code GitHub Actions with cloud providers。

手動安裝

1. 安裝 Claude GitHub App。把 Claude GitHub App 安裝到倉庫。這個 Action 依賴 App 的三項權限：

• Contents：讀寫，Claude 才能修改倉庫檔案。
• Issues：讀寫，Claude 才能回應 Issue。
• Pull requests：讀寫，Claude 才能建立 PR 並推送改動。

安裝時你還會授予其他 Claude 功能用到的權限，完整列表見下文“GitHub App 權限”。

2. 新增認證金鑰。按你的認證方式，在倉庫裡新增下面其中一個金鑰。GitHub 的做法見 using secrets in GitHub Actions。

• ANTHROPIC_API_KEY：來自 Claude Console 的 Claude API key。
• CLAUDE_CODE_OAUTH_TOKEN：用你的 Claude 訂閱認證的 OAuth 令牌，Pro、Max、Team 和 Enterprise 套餐可用，在本地執行 claude setup-token 生成。

在工作流檔案裡，把金鑰傳給對應的輸入：API key 用 anthropic_api_key，OAuth 令牌用 claude_code_oauth_token。

3. 複製工作流檔案。把 examples/claude.yml 複製到倉庫的 .github/workflows/ 目錄。這個檔案本身就是可以直接工作的工作流。按提交時的樣子，只要有人在 Issue 或 PR 裡提及 @claude，Claude 就會響應，並使用 ANTHROPIC_API_KEY 金鑰認證。如果你新增的是 CLAUDE_CODE_OAUTH_TOKEN，把工作流裡的 anthropic_api_key 那一行改成 claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}。

安裝完成後，在 Issue 或 PR 評論裡 @claude 測試一下。

為整個組織配置

快速安裝和手動安裝一次只配一個倉庫。要在組織裡推廣：

• 在組織層面安裝一次 Claude GitHub App，選全部倉庫或一個選定的列表。
• 把認證金鑰存成組織級別的 Actions 金鑰，每個倉庫不用各存一份。
• 給每個要執行這個 Action 的倉庫加上工作流檔案，或者把作業定義成一個可複用工作流，讓各倉庫呼叫。

跨倉庫共享的金鑰，用 Claude Console 的 API key，不要用 OAuth 令牌，因為 OAuth 令牌繫結的是執行 claude setup-token 那個人的訂閱。想完全不存長期金鑰，可以用工作負載身份聯合：Action 把工作流的 GitHub OIDC 令牌透過 Claude Console 的服務賬號換成 Claude API 訪問。需要設定的輸入是 anthropic_federation_rule_id、anthropic_organization_id，以及可選的 anthropic_service_account_id 和 anthropic_workspace_id，並給工作流 id-token: write 權限。Console 一側的配置見 Action 的 setup 指南。

GitHub App 權限

Claude GitHub App 由所有接入 GitHub 的 Claude 功能共用，包括這個 Action、Code Review，以及雲端工作階段裡的 PR 自動修復。一個 GitHub App 只有一套權限，所以其中有些權限這個 Action 並不使用。安裝時你會授予：

安裝 App 就是接受它的全部權限，GitHub 不允許只接受一部分。如果你的組織只允許這個 Action 用到的權限，可以按 Action 的 setup 指南建立一個只有 Contents、Issues 和 Pull requests 的自定義 GitHub App。自定義 App 只覆蓋這個 Action，Code Review 和網頁端自動修復仍然需要官方 App。

基本工作流：響應 @claude

下面這個工作流以互動模式執行 Action：有人在 Issue 或 PR 評論裡提及 @claude，Claude 就響應。

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

這個工作流裡不屬於樣板的部分：

• id-token: write：Action 預設的 GitHub App 認證需要它。
• actions: read：讓 Claude 能讀 PR 上的 CI 結果。
• actions/checkout：給 Claude 一份倉庫的本地副本來工作。
• if：避免在沒有提及 @claude 的評論上啟動 runner。Action 在響應之前也會自己檢查觸發短語。

工作流就位後，在任意 Issue 或 PR 評論裡 @claude 並寫出請求：

@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 在同一個 Issue 或 PR 裡用一條評論回覆，並在工作過程中更新它。

互動模式、自動化模式和誰能觸發

Action 根據工作流配置判斷怎麼執行：

• 互動模式：工作流沒有 prompt 輸入時，Claude 等待觸發短語（預設是 @claude），可以出現在 Issue 或 PR 評論裡、PR 審查裡，或者新開 Issue 的正文或標題裡，然後響應這個請求。進度和結果以評論形式出現在觸發它的 Issue 或 PR 上。
• 自動化模式：工作流提供了 prompt 輸入時，Claude 不等提及就執行，只受下面“誰能觸發”的檢查限制。預設情況下，結果出現在工作流執行日誌裡，而不是評論裡。如果 prompt 指示它發帖，並且它有能發帖的工具，Claude 可以發到 Issue 或 PR 上。

兩種模式下，Action 在 Claude 啟動之前都會對觸發者做兩項檢查，任何一項不透過，執行就失敗：

• 寫權限：對 Issue 和 PR 事件，觸發的使用者必須對倉庫有寫權限。要放行沒有寫權限的特定使用者，設定 allowed_non_write_users 並傳入你自己的 github_token 輸入。沒有使用者作為作者的事件，比如 schedule 觸發，跳過這一項檢查。
• 人類觸發者：對每種事件，Action 都會拒絕 bot 觸發者，除非你把它列在 allowed_bots 裡，以免 bot 讓 Claude 陷入迴圈觸發。這項檢查同樣適用於定時執行：GitHub 把定時執行算到某個倉庫使用者頭上，通常是最後改過工作流 cron 的那個人；如果這個使用者是 bot，就把它列進 allowed_bots。

常用引數

這些是最常用的輸入，每個都對應 anthropics/claude-code-action 這一步裡的一個 with: 鍵。

完整的輸入列表見 Action 的配置參考。

用 claude_args 傳 CLI 引數

claude_args 接受任何 Claude Code CLI 引數：

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

常用引數：

• --max-turns：限制對話輪數。
• --model：使用的模型，例如 claude-sonnet-5。不傳這個引數時，Action 使用 Claude Code 的預設模型。
• --mcp-config：MCP 配置的路徑。
• --allowedTools：允許使用的工具，逗號分隔。--allowed-tools 這個別名也可以用。
• --debug：開啟除錯輸出。

更多用法示例

官方的 examples 目錄裡有各種場景的現成工作流。本頁的示例都用 API key 認證；如果你用 Claude 訂閱認證，把任何示例裡的 anthropic_api_key 那一行換成 claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}。

在 PR 上自動審查（執行技能）

prompt 輸入除了純文字，也接受技能呼叫：

• 倉庫 .claude/skills/ 目錄裡的技能：在 anthropics/claude-code-action 這一步之前執行 actions/checkout，讓技能檔案在 runner 上可用，然後把 /skill-name 作為 prompt。
• 打包在外掛裡的技能：用 plugin_marketplaces 和 plugins 輸入安裝外掛，然後把帶名稱空間的 /plugin-name:skill-name 作為 prompt。plugins 輸入的格式是 plugin-name@marketplace-name，其中市場名來自市場自己的清單，而不是它的倉庫 URL。

下面的工作流安裝 code-review 外掛，並在 PR 被開啟、更新、重新開啟或標記為可審查時執行它的技能。它和快速安裝裡的審查工作流用的是同一個外掛。想自己控制 prompt、模型和觸發條件時用這樣的工作流。在公開倉庫裡，GitHub 不會把金鑰交給 fork 的 PR 觸發的執行，所以這個審查只會在同一倉庫分支發起的 PR 上執行。

name: Code Review
on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: read
      issues: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          plugin_marketplaces: "https://github.com/anthropics/claude-plugins-official.git"
          plugins: "code-review@claude-plugins-official"
          prompt: "/code-review:code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"
          claude_args: '--allowedTools "mcp__github_inline_comment__create_inline_comment"'

這個工作流裡有兩行決定審查發到哪裡：

• --comment：Claude 把審查發在 PR 上，發現的每個問題發一條行內評論，沒發現問題就發一條彙總評論。不加它，Claude 什麼都不發，你要到工作流執行日誌裡看結果。
• claude_args：即使技能自己的 allowed-tools frontmatter 已經列出同一個工具，也要保留這一行，因為只有 claude_args 裡的 --allowedTools 點名了它，Action 才會啟動發行內評論的 MCP 伺服器。

Claude 會跳過草稿和已關閉的 PR、它判斷不需要審查的 PR（比如自動生成的或很小的改動），以及已經有 Claude 評論的 PR。

按計劃執行

有 prompt 輸入時，Action 在任意 GitHub 事件上以自動化模式執行，包括 cron 定時。對純文字 prompt，在你授予 prompt 所需的工具之前，Claude 沒有 shell 或 GitHub API 的訪問權限：用 claude_args 裡的 --allowedTools，或 settings 輸入裡的 permissions.allow 規則。如果呼叫的是技能，Claude 可以使用技能 allowed-tools frontmatter 授予的工具。GitHub 只從預設分支執行定時工作流，並且在公開倉庫裡，倉庫 60 天沒有活動後會停用定時。

下面的工作流每天 09:00 UTC 在工作流執行日誌裡生成一份報告。它的 claude_args 選定模型並允許兩個 GitHub MCP 工具。Claude 透過這些工具經 GitHub API 讀取提交和 Issue，所以可以省掉 checkout 步驟：

name: Daily Report
on:
  schedule:
    - cron: "0 9 * * *"
jobs:
  report:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: read
      id-token: write
    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 claude-opus-5-5
            --allowedTools "mcp__github__list_commits,mcp__github__list_issues"

用 CLAUDE.md 定義專案規範

在倉庫根目錄建立 CLAUDE.md，寫下程式碼風格指南、審查標準、專案專屬規則和偏好的寫法。Claude 建立 PR 和響應請求時會遵循這些規範。CLAUDE.md 的寫法見 CLAUDE.md 配置。

安全：金鑰和權限

警告：永遠不要把 API key 或 OAuth 令牌直接提交進倉庫。始終把它們存成 GitHub Secrets，並在工作流裡引用，例如 anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}。

• 只給工作流它需要的權限，並在合併之前檢查 Claude 的改動。
• 要讓這個 Action 在不存長期金鑰的情況下認證，可以用上文的工作負載身份聯合。
• 刪除金鑰並不會讓憑據失效：要徹底停用一個 API key，還要在 Claude Console 裡刪除這個 key。
• 權限和認證方面更詳細的指導，見 Claude Code Action 安全文件。資料處理和保留問題見官方的 data usage 和 security 頁面。

想給 Claude 的工具使用加規則，可以參考 權限模式 和 Hooks 兩篇，它們講的是 Claude Code 本身的機制。

費用和用量

每次執行消耗兩類資源：

• GitHub Actions 分鐘數：Action 執行在 GitHub 託管的 runner 上，消耗你的 Actions 分鐘數。價格和分鐘數上限見 GitHub 的計費文件。
• API token：每次互動消耗的 token 取決於 prompt 和回覆的長度、任務複雜度和程式碼庫大小。當前 token 價格見 Claude 的定價頁。如果你用 OAuth 令牌認證，執行使用的是你的 Claude 訂閱，而不是 API 計費。

想同時降低兩類成本，給 Claude 更清晰的上下文，並限制每次執行的工作量：

• 把 @claude 的請求寫具體，Claude 需要的輪數就更少。
• 用 Issue 模板把上下文提前給全。
• 讓 CLAUDE.md 保持簡短，因為 Claude 每次執行都會讀它。
• 在 claude_args 裡設定 --max-turns 限制迭代次數。
• 設定工作流級別的超時，避免作業失控。
• 用 GitHub 的併發控制限制並行執行數。

常見問題排查

Claude 不響應 @claude

• 確認 GitHub App 已安裝在這個倉庫上。
• 檢查倉庫已啟用工作流。
• 確認你的 API key 或 OAuth 令牌已設定在倉庫金鑰裡。
• 確認評論裡的 @claude 是一個完整的詞，不是 /claude 或 @claude-bot。
• 確認評論的使用者對倉庫有寫權限，例外情況見上文“誰能觸發”。

Claude 的提交沒有觸發 CI

• GitHub 不會對用預設 GITHUB_TOKEN 做的提交觸發工作流。如果你給 Action 傳了 github_token: ${{ secrets.GITHUB_TOKEN }}，刪掉它，讓 Action 以 Claude GitHub App 的身份認證，或者改傳一個自定義 App 的令牌。
• 檢查你的 CI 工作流的觸發條件包含 Claude 推送產生的事件，比如 push 或 pull_request。

認證錯誤

• 在除錯工作流之前，先在本地用 claude 測試，確認 API key 或 OAuth 令牌有效。
• Bedrock、Agent Platform 和 Foundry 的認證問題，看雲服務商那一頁的排錯部分。

更多解決辦法見 Action 的 FAQ。

解除安裝和從 beta 升級

• 工作流檔案：刪除 .github/workflows/ 裡使用 anthropics/claude-code-action 的工作流。用快速安裝的話，找 claude.yml，選了審查工作流的話還有 claude-code-review.yml。
• 金鑰：從倉庫裡刪除 ANTHROPIC_API_KEY 或 CLAUDE_CODE_OAUTH_TOKEN 金鑰，如果共享給了多個倉庫，也要從組織級別的 Actions 金鑰裡刪除。
• GitHub App：在倉庫或組織設定的 GitHub Apps 下解除安裝 Claude GitHub App，但前提是你沒有把它用於其他 Claude 功能，比如 Code Review 或網頁端自動修復。
• 如果工作流還引用 anthropics/claude-code-action@beta，升級到 v1：把 uses 行裡的 @beta 改成 @v1；刪掉 mode 輸入，因為 Action 現在自動檢測模式；把 direct_prompt 換成 prompt；把 max_turns 和 model 這類 CLI 選項移進 claude_args。

常見問題

來源

• Claude Code GitHub Actions（安裝、工作流示例、引數、權限、費用、排錯，2026 年 10 月 30 日核對）