Claude Code 在 CI 裏跑：從本機 claude -p 到 GitHub Actions 的完整例子（自動審 PR、控成本）

本文根據 Claude Code 官方《Claude Code GitHub Actions》和《Run Claude Code programmatically》整理，資料核對於 2026-11-05。配圖為本站整理的示意圖，不是介面截圖。工作流裏的提示詞和參數組合是本站自己擬的示例。本站（bigolab.com）不是 Anthropic 官方網站。

適用於誰

• 已經看過 /guides/claude-code-headless-mode 和 /guides/claude-code-github-actions，但想看一個從頭到尾串起來的例子的人；
• 想讓每個 PR 自動過一遍 Claude 審查，又擔心費用失控的團隊；
• 想先在本機把命令調通，再放進 CI 的人。

結論先說

1. 先本機，後 CI：同一段提示詞、同樣的 --allowedTools，在本機用 claude -p 跑通再搬到工作流裏，排錯成本最低。
2. CI 裏用 --bare：官方說它能讓每台機器得到一致的結果，不會讀到別人 ~/.claude 裏的 hook 或項目 .mcp.json 裏的伺服器；它不讀訂閱登入，要設定 ANTHROPIC_API_KEY。
3. GitHub Actions 裏有 prompt 就是自動化模式：不等 @claude 評論，直接按觸發事件運行；預設結果只寫在工作流日誌裏。
4. 權限要顯式給：官方寫明自動化模式下，普通文本提示詞沒有 shell 和 GitHub API 權限，除非用 --allowedTools 或 permissions.allow 授予。
5. 成本靠三道閘：--max-turns、工作流超時、並發限制，加上一份簡短的 CLAUDE.md。

圖：本站根據 Claude Code 官方《Claude Code GitHub Actions》 整理的示意圖

一、第一步：本機用 claude -p 跑通

假設要做的事是「審查當前分支相對 main 的改動，只報嚴重問題」。官方有現成的管道寫法：把 diff 通過標準輸入交給 Claude，它就不需要 Bash 權限去讀 diff。先試一個最樸素的版本：

bash
git diff main...HEAD | claude --bare -p "你是代碼審查員。只指出會導致 bug 或安全問題的改動，每條一行：文件名:行號 問題。沒有問題就只回復 OK。"

要讓腳本能判斷結果，用官方的 --output-format json 加 --json-schema，結構化結果在 structured_output 字段裏：

bash
git diff main...HEAD | claude --bare -p "審查這份 diff，列出嚴重問題" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"issues":{"type":"array","items":{"type":"string"}}},"required":["issues"]}' \
  | jq '.structured_output.issues'

兩個官方提醒要放進腳本：

• 如果運行結束時沒有有效的結構化輸出（比如 Claude 拒絕了請求），響應裏沒有 structured_output 字段，所以腳本里要先判斷字段存在，再使用；
• 退出碼：成功是 0，失敗是非 0。不過官方也說，運行過程中的失敗（比如缺少認證）會把失敗資訊作為結果打印到標準輸出，所以不要只看退出碼。

輸入有 10MB 的上限：超過會報錯退出，大改動要先寫到文件再在提示詞裏引用路徑。

先在本機確認輸出符合預期，再往下走。可以在 claude -p 的結果裏看到 total_cost_usd（官方說這是客戶端估算，可能與帳單有出入），用來估一個 PR 大概花多少。

二、第二步：把審查標準寫進 CLAUDE.md

CI 裏每次運行都會讀倉庫裏的 CLAUDE.md（不加 --bare 時；GitHub Action 按官方最佳實踐頁的說法同樣會遵循它）。把審查口徑寫進去，比每次改工作流裏的提示詞方便：

markdown
## 代碼審查
- 只關注：會導致運行錯誤、數據丟失、越權或密鑰泄露的改動
- 不要評論代碼風格，格式問題由 lint 負責
- 每條意見寫明文件名和行號

官方提醒要保持精簡，因為它每次運行都會被讀入。寫法參考 /guides/claude-code-claude-md-templates-frontend-backend-data。

三、第三步：配置密鑰與應用

官方推薦的快速路徑：在倉庫裏打開 claude，運行 /install-github-app，它會安裝 Claude GitHub App、儲存倉庫密鑰，並推一個帶工作流文件的分支、幫你打開創建 PR 的頁面。這條命令只對 github.com 倉庫有效，需要你有倉庫管理員權限，並先安裝、登入 GitHub CLI（gh auth login）。

手動配置時：安裝 Claude GitHub App；在倉庫 Secrets 中添加 ANTHROPIC_API_KEY（Claude Console 的 API Key），或者訂閱用戶用 claude setup-token 生成令牌存為 CLAUDE_CODE_OAUTH_TOKEN。官方特別寫了：永遠不要把 Key 提交進倉庫，只放 Secrets。多個倉庫共享時，官方建議用 API Key 而不是 OAuth 令牌，因為令牌綁定的是運行 setup-token 那個人的訂閱。訂閱和 API 的取捨見 /guides/claude-code-pro-max-or-api。

四、第四步：寫自動審查的工作流

下面的觸發事件、權限塊和 action 版本取自官方示例的寫法，prompt 和 claude_args 是本站按官方說明拼的：

yaml
name: Claude PR Review
on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]

concurrency:
  group: claude-review-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  review:
    if: github.event.pull_request.draft == false
    runs-on: ubuntu-latest
    timeout-minutes: 15
    permissions:
      contents: read
      pull-requests: read
      issues: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            審查本 PR 相對 ${{ github.base_ref }} 的改動，只報嚴重問題，按 CLAUDE.md 的「代碼審查」要求。
            用 git diff 查看改動，輸出文件名:行號和問題；沒有問題就寫 OK。
          claude_args: |
            --max-turns 8
            --allowedTools "Read,Grep,Glob,Bash(git diff *),Bash(git log *)"

逐段說明：

• on.pull_request.types：官方審查示例用的同一組事件；
• concurrency 與 cancel-in-progress：同一個 PR 連續推送時取消舊的運行，對應官方成本建議裏的「使用 GitHub 並發控制限制並行運行」；
• timeout-minutes：對應「設定工作流級超時避免跑飛」；
• id-token: write：官方說明這是 action 預設使用 GitHub App 認證所需；
• prompt 一旦存在，就是自動化模式，不再等待 @claude；
• --max-turns 8：官方 claude_args 的常見參數，限制回合數；
• --allowedTools：自動化模式下授予 shell 與讀取權限，Bash(git diff *) 的寫法是官方的前綴匹配語法；
• fetch-depth: 0：本站補充，為了能比較 base 分支，官方示例用的是 1，如果你只需要看改動文件的內容可以保留 1。

結果去哪裏看：官方寫明，自動化模式預設結果出現在工作流運行日誌裏。若希望審查意見直接成為 PR 上的評論，官方的現成做法是安裝 code-review 插件並帶 --comment（官方「Run a skill」一節），以及在 claude_args 裏允許 mcp__github_inline_comment__create_inline_comment。官方還說明：公開倉庫裏來自 fork 的 PR 拿不到 Secrets，所以審查只對同倉庫分支的 PR 生效。

五、同一個倉庫再加「@claude 隨叫隨到」

自動審查之外，官方最基本的工作流是讓評論裏的 @claude 觸發（交互模式，不寫 prompt）：

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:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

官方指出觸發者必須有倉庫寫權限，機器人帳號預設會被拒絕，以防循環觸發。

六、出問題先看哪裏

圖：本站根據 Claude Code 官方《Claude Code GitHub Actions》 整理的示意圖

官方排查頁的要點：評論 @claude 沒反應，檢查 GitHub App 是否安裝、工作流是否啟用、Secrets 是否設定、評論裏是否是完整的 @claude 單詞、評論者是否有寫權限；Claude 推送的提交沒觸發 CI，是因為用預設 GITHUB_TOKEN 提交的代碼不會觸發工作流，去掉傳給 action 的 github_token；認證失敗，先在本機用同一個 Key 或令牌運行 claude 驗證。

常見問題

Q：一次審查大概花多少錢？

官方不給固定數字，只說取決於提示詞和回覆長度、任務複雜度、代碼庫大小，價格以官方定價頁為準。可以用本機 JSON 輸出裏的 total_cost_usd 做估算。

Q：用訂閱還是 API？

訂閱令牌適合個人倉庫，團隊共享用 API Key，詳見第三節。想了解訂閱方案可看 Claude Code 訂閱方案。

相關教學

• /guides/claude-code-headless-mode
• /guides/claude-code-github-actions
• /guides/claude-code-permission-modes

參考資料

• Claude Code 官方：Claude Code GitHub Actions — https://code.claude.com/docs/en/github-actions
• Claude Code 官方：Run Claude Code programmatically — https://code.claude.com/docs/en/headless