Claude Code GitHub Actions 配置教學：@claude 自動審 PR、修 issue

本文根據 Claude Code 官方文檔《Claude Code GitHub Actions》和官方倉庫 anthropics/claude-code-action 整理，核對日期 2026-10-07。示例工作流改寫自官方示例。

適用於誰

• 想在 GitHub 的 issue 或 PR 評論裏 @claude，讓它分析代碼、改代碼、提交 PR 的開發者；
• 想每次開 PR 都自動跑一遍 AI 代碼審查的團隊；
• 搜「claude code github actions」「pr review」「max plan」想知道能不能用訂閱額度跑的人。

結論先說

1. Claude Code GitHub Actions 是官方的 GitHub Action（anthropics/claude-code-action），在你倉庫的工作流裏運行 Claude Code。
2. 最快的配置方式：本地進入倉庫運行 claude，輸入 /install-github-app，它會安裝 Claude GitHub App、儲存密鑰並幫你準備好工作流 PR，合併後就能用。需要倉庫管理員權限。
3. 認證二選一：CLAUDE_CODE_OAUTH_TOKEN（用 Pro / Max / Team / Enterprise 訂閱，claude setup-token 生成）或 ANTHROPIC_API_KEY（Claude Console 的 API Key，按 API 用量計費）。
4. 兩種運行模式：工作流裏沒有 prompt 時是交互模式，等人 @claude；有 prompt 時是自動化模式，按觸發事件直接運行（比如開 PR、定時）。
5. 每次運行同時消耗 GitHub Actions 分鐘數和 Claude 用量，記得用 --max-turns、超時和並發控制限制開銷。

方式一：快速配置（推薦）

1. 安裝 GitHub CLI 並登入：gh auth login；
2. 在要接入的倉庫裏運行 claude，輸入：

text
   /install-github-app
   

1. 按提示操作：安裝 Claude GitHub App → 選擇認證方式（用訂閱生成長期令牌，或粘貼 API Key）→ 選擇要添加的工作流（基礎的 @claude 響應，以及可選的 PR 審查）；
2. Claude Code 會把密鑰儲存為倉庫 Secret（API Key 叫 ANTHROPIC_API_KEY，訂閱令牌叫 CLAUDE_CODE_OAUTH_TOKEN），推送一個包含工作流文件的分支，並在瀏覽器裏打開創建 PR 的頁面；
3. 創建併合並這個 PR，@claude 就能在倉庫裏用了。

這個命令只支持 github.com 上的倉庫；GitLab 請看官方的 GitLab CI/CD 文檔。中途按 Esc 可以停止，結束資訊會列出已經做了哪些操作。

方式二：手動配置

1. 安裝 Claude GitHub App：打開 github.com/apps/claude 安裝到倉庫。Action 實際依賴的是三項權限：Contents、Issues、Pull requests 的讀寫；
2. 添加倉庫 Secret（Settings → Secrets and variables → Actions）：

• ANTHROPIC_API_KEY：Claude Console 的 API Key；
• 或 CLAUDE_CODE_OAUTH_TOKEN：在本地運行 claude setup-token 生成的訂閱令牌；

1. 複製工作流文件：把官方倉庫的 examples/claude.yml 放進 .github/workflows/。

一個最小的 @claude 響應工作流：

yaml
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:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

用 API Key 的話，把最後一行換成 anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}。其中 id-token: write 是 Action 預設用 GitHub App 認證所必需的，actions: read 讓 Claude 能讀到 PR 上的 CI 結果，if 條件避免沒提到 @claude 的評論也啟動運行器。

合併後，在 issue 或 PR 評論裏這樣用：

text
@claude 根據 issue 描述實現這個功能
@claude 這個接口的用戶認證應該怎麼實現？
@claude 修復用戶面板組件裏的 TypeError

Claude 會在同一個 issue / PR 下回復，並隨進度更新評論。

訂閱令牌還是 API Key？

官方建議：跨倉庫共享的組織級 Secret 用 API Key，因為訂閱令牌綁定的是生成它的那個人的訂閱。也可以用工作負載身份聯合（OIDC），完全不存長期密鑰，配置見 Action 倉庫的 setup 文檔。

自動化示例

每個 PR 自動代碼審查

用 prompt 調用官方 code-review 插件裏的技能，PR 打開、更新、重新打開或轉為可審閱時運行：

yaml
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-code.git"
          plugins: "code-review@claude-code-plugins"
          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 讓審查結果以行內評論（或一條彙總評論）發到 PR 上，不加的話只寫在運行日誌裏；
• claude_args 這一行不能省：只有在這裏用 --allowedTools 點名，Action 才會啟動發行內評論的 MCP 伺服器；
• Claude 會跳過草稿和已關閉的 PR、它判斷不需要審的 PR（如自動生成或很小的改動），以及已有它評論的 PR；
• 公開倉庫裏，來自 fork 的 PR 拿不到 Secret，所以只審同倉庫分支的 PR。

不想維護工作流文件，官方另有「Code Review」功能，可以對每個 PR 自動審查。

定時任務：每天生成一份報告

yaml
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: "彙總昨天的提交和當前未關閉的 issue"
          claude_args: |
            --allowedTools "mcp__github__list_commits,mcp__github__list_issues"

純文本 prompt 預設沒有 shell 和 GitHub API 權限，要用 --allowedTools 授予需要的工具。注意 GitHub 只從預設分支運行定時工作流，公開倉庫 60 天無活動會自動停用定時任務；cron 用的是 UTC 時間（上例為 UTC 9 點，即北京時間 17 點）。

常用參數

最佳實踐

• 在倉庫根目錄寫好 CLAUDE.md：代碼風格、審查標準、項目規則，Claude 每次運行都會讀（所以也要寫得精簡）。CLAUDE.md 寫法詳見本站《CLAUDE.md 怎麼寫：最佳實踐、模板與 AGENTS.md 的區別》。
• 密鑰只放 GitHub Secrets，永遠不要提交到倉庫；工作流只給必要的權限；合併前人工檢查 Claude 的改動。
• 控制成本：@claude 請求寫具體；用 issue 模板提前提供上下文；claude_args 裏加 --max-turns；給工作流設超時；用 GitHub 並發控制限制同時運行的數量。

常見問題

Q：@claude 了沒反應？

官方檢查清單：確認 GitHub App 已裝到這個倉庫；倉庫啟用了 Actions 工作流；Secret 已設定；評論裏是完整的 @claude（不是 /claude 或 @claude-bot）；評論者對倉庫有寫權限（沒有寫權限的用戶預設不能觸發）。

Q：Claude 提交的代碼沒有觸發 CI？

GitHub 不會因為預設 GITHUB_TOKEN 做的提交觸發工作流。如果你給 Action 傳了 github_token: ${{ secrets.GITHUB_TOKEN }}，刪掉它讓 Action 以 Claude GitHub App 身份提交，或者換成自定義 App 的令牌；同時確認 CI 的觸發條件包含 push / pull_request。

Q：認證報錯？

先在本地用同樣的 Key / 令牌運行 claude 確認有效，再排查工作流。

Q：安裝 App 時要的權限比 Action 用到的多？

Claude GitHub App 是 Action、Code Review、雲端自動修 PR 等功能共用的，GitHub 不允許只接受部分權限。組織只想給最小權限的話，可以按 Action 倉庫的 setup 文檔自建一個只含 Contents、Issues、Pull requests 的 GitHub App（但 Code Review 等功能仍需官方 App）。

Q：以前用的是 @beta 版本？

把 uses 改成 @v1，刪掉 mode 輸入（現在自動判斷模式），direct_prompt 改名為 prompt，max_turns、model 等挪進 claude_args。

參考資料

• Claude Code GitHub Actions（官方）：https://code.claude.com/docs/en/github-actions
• Code Review（官方）：https://code.claude.com/docs/en/code-review
• Authentication · Generate a long-lived token（官方）：https://code.claude.com/docs/en/authentication
• anthropics/claude-code-action（官方倉庫）：https://github.com/anthropics/claude-code-action