Claude Code GitHub Actions 教學:@claude 修 issue、PR 自動審查,訂閱 token 定 API key 點揀
按 Anthropic 現行官方文件(2026 年 9 月 15 日核對)設定 Claude Code GitHub Actions:用 /install-github-app 快速設定,或手動安裝 Claude GitHub App、加 Secret、放 workflow,再留言 @claude 改 code 及開 PR 自動審查。另有訂閱 token 與 API key 之選、成本、安全設定同排錯。文首附支援地區狀態。
本頁內容

難度
中階
所需時間
30–45 分鐘(首次設定;不計 workflow 執行時間)
你需要準備
Claude Code(執行 /install-github-app 或 claude setup-token) · GitHub CLI(gh,只限快速設定) · github.com 上的 repo 及 GitHub Actions · Claude GitHub App
開始之前
- 目標 repo 的 admin 權限(兩種設定方法都需要),而 repo 要放在 github.com
- Claude Pro、Max、Team 或 Enterprise 方案(用訂閱 token),或 Claude Console 的 API key(按 API 計費);Claude 免費方案不包括 Claude Code
- 快速設定:本機已安裝 Claude Code,以及已用 gh auth login 驗證的 GitHub CLI
- 所在地屬 Anthropic 官方支援國家/地區(見文首方格;截至 2026-09-15 香港不在名單內)
- 建議先用一個測試 repo 或非關鍵 PR 練習,確認權限範圍和留言位置
想 Claude 在 GitHub 幫你審查 PR、按 issue 改 code,而唔使自己開終端機,就要用 Claude Code GitHub Actions。它是 Anthropic 官方的 GitHub Action(anthropics/claude-code-action),在你 repo 的 workflow 內執行 Claude Code:你在 PR 或 issue 留言提到 @claude,Claude 會分析程式碼、實作改動並 push commit;你亦可以給它一個 prompt,讓它在任何 GitHub 事件自動執行。本文按官方文件整理兩種設定方法、第一個 workflow、PR 自動審查、訂閱 token 與 API key 的選擇、成本、安全設定和常見錯誤。
支援地區(2026 年 9 月 15 日核對):截至 2026-09-15,香港並不在 Anthropic 官方支援國家/地區名單內,該名單同時涵蓋 Commercial API 及 Claude.ai。Claude Code GitHub Actions 無論用訂閱 token 還是 API key 認證,都是使用 Anthropic 的服務,同樣受這份名單規限。名單會變,設定或付款前請自行重查。本文只介紹官方設定步驟,並不代表你符合使用資格,也不提供 VPN、外地地址、借用電話、他人身份或共用帳戶等任何規避方法;香港用家請先讀 Claude 香港訂閱指南。
一句答案:設定只有三件事:在 repo 安裝 Claude GitHub App、加一個 Secret、放一個使用 anthropics/claude-code-action@v1 的 workflow。Secret 二揀一:用 Pro、Max、Team 或 Enterprise 訂閱,就用 claude setup-token 產生的 CLAUDE_CODE_OAUTH_TOKEN;想按 API 計費,就用 Claude Console 的 ANTHROPIC_API_KEY。最快的做法是在 repo 內開 Claude Code,執行 /install-github-app,三件事它都會代你準備好。兩種方法都需要該 repo 的 admin 權限。
資料核對日期:2026 年 9 月 15 日。本文的步驟、設定名稱和 YAML 都以 Anthropic 的 Claude Code GitHub Actions 官方文件為準,YAML 照錄官方範例;截至同日,action 的主要版本仍是 v1。如果畫面或指令與本文不同,以官方文件為準。本站沒有自行量度 Claude 的審查質素或每次執行的用量;文中標明「示例」的留言,只作說明用途,不是實際輸出。
先分清楚:GitHub Actions、Code Review、/code-review
Anthropic 有幾樣產品都用 Claude Code 這個名字,其中三樣都與 GitHub PR 有關,最容易混淆:
| 產品 | 適用方案 | 怎樣觸發 | 收費 |
|---|---|---|---|
| Claude Code GitHub Actions(本文) | Pro、Max、Team、Enterprise 訂閱 token,或 API key | 在 issue/PR 留言 @claude,或由 workflow 內的 prompt 按事件執行 | 訂閱 token:用你的訂閱;API key:按 token 計費;另加 GitHub Actions 分鐘 |
| Code Review(託管,research preview) | 只限 Team 和 Enterprise;開啟 Zero Data Retention 的機構不可用 | 由機構 Owner 開啟後,按設定在 PR 開啟、每次 push 或留言 @claude review 時執行 | 每次審查平均 US$15–25,經 usage credits 另計,不計入方案內含用量 |
本機 /code-review | 其他方案都可用 | 在本機 Claude Code 輸入 /code-review | 屬一般 Claude Code 使用 |
換言之,Pro 和 Max 用家想在 GitHub 自動審查 PR,要用的是本文的 Actions 審查 workflow(或本機 /code-review),而不是託管的 Code Review。資料來源:Code Review 官方文件。
開始前要準備乜
| 項目 | 官方要求 | 要留意 |
|---|---|---|
| Repo 權限 | 目標 repo 的 admin 權限 | 快速設定和手動設定都需要 |
| Git 平台 | github.com | /install-github-app 只支援 github.com;remote 在 gitlab.com 或 bitbucket.org 時,指令會顯示通知並退出。GitLab 和 GitHub Enterprise Server 另有官方文件 |
| Claude 帳戶 | Pro、Max、Team 或 Enterprise(訂閱 token),或 Claude Console API key | Claude 免費方案不包括 Claude Code |
| 本機工具(只限快速設定) | 已安裝 Claude Code;已安裝 GitHub CLI 並執行 gh auth login | Claude Code 會檢查 GitHub CLI,缺少時會警告 |
| 所在地 | Anthropic 支援國家/地區 | 見文首方格 |
未安裝 Claude Code,先看 Claude Code 安裝教學。第一次設定,建議先用一個測試 repo,確認 Claude 可以存取的範圍和留言位置,才推到正式 repo。
用訂閱 token 定 API key?
Workflow 要用一個憑證向 Anthropic 認證。官方提供以下幾種方式,分別在於誰付款、適合誰:
| 方式 | Secret/設定 | 點樣產生 | 計費 | 適合 | 要留意 |
|---|---|---|---|---|---|
| 訂閱 OAuth token | CLAUDE_CODE_OAUTH_TOKEN,傳入 claude_code_oauth_token | 在本機執行 claude setup-token | 用你的 Claude 訂閱,不按 API 計費 | 個人開發者在自己的 repo 使用 | 有效期一年;綁定執行 setup-token 那個人的訂閱;只可以發出模型請求,不能建立 Remote Control session,亦讀取不到 claude.ai connectors |
| API key | ANTHROPIC_API_KEY,傳入 anthropic_api_key | 在 Claude Console 建立 | 按 token 收費,視乎 prompt 和回應長度、任務複雜度、codebase 大小 | 團隊、多個 repo 或 organization 共用 | 刪除 GitHub Secret 不會令 key 失效,要在 Console 一併刪除 |
| Workload identity federation | anthropic_federation_rule_id、anthropic_organization_id 等 input,加 id-token: write | 在 Claude Console 設定 service account 和 federation rule | 經 Claude API 計費 | 不想存放長期 Secret 的團隊 | 用 workflow 的 GitHub OIDC token 交換 Claude API 存取權 |
| 雲端供應商 | use_bedrock、use_vertex 或 use_foundry | 在 Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry 設定 | 經你的雲端帳戶 | 已使用這些平台的機構 | 以 OIDC 身份聯合認證,repo 內不存靜態雲端憑證;本文不詳述 |
團隊唔好共用一個人的訂閱 token。官方文件寫明,OAuth token 綁定執行 claude setup-token 那個人的訂閱,所以要在多個 repo 共用的 Secret,官方建議改用 Claude Console 的 API key。Anthropic 的 Claude Code 法律與合規頁亦說明,Pro 和 Max 宣傳的用量上限,是以一般、個人使用 Claude Code 為前提;OAuth 認證只供訂閱方案的購買者作一般用途。Consumer Terms 則禁止把帳戶登入資料、API key 或帳戶憑證交給其他人。所以,訂閱 token 適合個人開發者在自己的 repo 使用,只由產生它的人保管;團隊共用的 repo,應該用 API key 或 workload identity federation,每位成員在本機則用自己的帳戶登入 Claude Code。任何聲稱「共用或轉交 token 很安全」的說法都不可信。
訂閱用量怎樣計:官方說明用 OAuth token 時,執行會用你的 Claude 訂閱而不是 API 計費;而 Pro 和 Max 的用量限制由 Claude 和 Claude Code 共用。官方沒有公布一次 workflow 會用多少用量,本文亦不作估算。
官方美元標價(Claude 官方價格頁及 Max 方案說明,2026-09-15 核對,不包括適用稅項,Anthropic 可隨時調整):Pro 月繳 US$20,年繳折合 US$17/月(US$200 一次過預繳);Max 5x US$100/月;Max 20x US$200/月。5x、20x 是相對 Pro 每個 session 的用量倍數,不是固定訊息數或執行次數。揀 Pro 定 Max,請看 Claude Code 要用邊個 Claude 方案;想比較官方訂閱、官方 API 和第三方中轉的資料流與條款,請看 Claude Code API 中轉風險。
本站的 Claude Code 方案服務頁列出相關 Claude 方案服務的內容;頁面上的港幣價錢是本站獨立服務總價,不是 Anthropic 官方香港價格。本站與 OpenAI/Anthropic 並無從屬關係;付款前請閱讀服務條款和服務流程說明,並了解代充與成品號涉及的憑證、條款和停權風險。任何方式都不會改變文首所述的官方支援地區狀態。
方法一:用 /install-github-app 快速設定
- 安裝 GitHub CLI,在終端機執行
gh auth login完成驗證。 - 在要連接的 repo 資料夾輸入
claude開啟 Claude Code,再輸入/install-github-app,按提示操作。 - Claude Code 會先安裝 Claude GitHub App,然後問你是否繼續設定 GitHub Actions。揀 Skip for now 就只安裝 App 便停止,之後再執行一次
/install-github-app完成 workflow 和 Secret(v2.1.187 之前的版本不會問,直接進入揀 workflow)。 - 設定認證:如果 Claude Code 已經有 API key,會沿用那條 key;repo 已有
ANTHROPIC_API_KEYSecret 時,亦會問你是否保留。否則你要揀「用 Claude 訂閱產生長期 token」或「貼上 API key」。Claude Code 會把憑證存成 repo Secret:API key 叫ANTHROPIC_API_KEY,訂閱 token 叫CLAUDE_CODE_OAUTH_TOKEN。 - 揀要加入的 workflow 檔案。Claude Code 會把這些檔案 push 到一條新 branch(檔案內已經設定為引用上一步那個 Secret,Secret 本身不會寫進檔案),並在瀏覽器打開 GitHub,準備好一個待建立的 pull request。
- 建立並 merge 這個 PR,之後在 issue 或 PR 留言
@claude測試。
- 想用訂閱,先確認沒有 API key:Claude Code 已有 API key 時會直接沿用,執行就會按 API 計費。開始前先用
/status確認目前的登入方式,詳見安裝教學中 ANTHROPIC_API_KEY 計費陷阱一節。 - 訂閱用家可以用快速設定:官方文件寫明 quick setup 同時支援 Claude API 和 Claude 訂閱。
claude-code-actionrepo 的 README 仍寫這個方法只供直接使用 Anthropic API 的用家,應以 code.claude.com 的現行文件為準。 - 審查 workflow:如果你同時揀了審查 workflow,由 v2.1.229 起,Claude 會把審查直接留在 PR 上;之前的版本只寫進 workflow run log(更新方法見下文「PR 自動審查」)。
- 權限:安裝 App 即授予它的整套權限,完整清單見下文「安全設定清單」。
方法二:手動設定三步
如果你不在本機跑 Claude Code、快速設定失敗,或者想完全控制 workflow 檔案,就用手動設定。
Step 1:安裝 Claude GitHub App
到 Claude GitHub App 頁面,把它安裝到你的 repo;在 organization 安裝時,可以揀全部 repo 或指定 repo。Action 依賴它其中三項權限:
- Contents:讀寫,讓 Claude 修改 repo 檔案。
- Issues:讀寫,讓 Claude 回應 issue。
- Pull requests:讀寫,讓 Claude 建立 PR 和 push 改動。
安裝時你亦會一併授予其他 Claude 功能用到的權限,完整清單見下文。
Step 2:加入認證 Secret
用訂閱:在本機終端機執行:
claude setup-token
指令會打開與 /login 相同的瀏覽器授權流程,你批准後,token 會在終端機顯示;Claude Code 不會把它儲存在任何地方,所以要即時複製。這條 token 有效期一年,需要 Pro、Max、Team 或 Enterprise 方案。建議即時在日曆記下一年後的日期,到期前換新。用 API key:到 Claude Console 建立一條 key。
然後按 GitHub 官方步驟加入 repo Secret:
- 在 GitHub 打開 repo 主頁,按 Settings。
- 在側欄「Security」部分揀 Secrets and variables,再按 Actions。
- 在 Secrets 分頁按 New repository secret。
- Name 填
CLAUDE_CODE_OAUTH_TOKEN(用 API key 就填ANTHROPIC_API_KEY),Secret 欄貼上 token 或 key。 - 按 Add secret。
Token 和 key 只放在 Secret:不要寫進 workflow 檔、CLAUDE.md、issue、PR 描述、聊天群組或截圖。如果要在多個 repo 共用 Secret,用 organization 層面的 Actions secret,並按官方建議改用 API key;另外,GitHub Free 的私人 repo 讀取不到 organization 層面的 Secret。
Step 3:複製 workflow 檔案
把官方 repo 的 examples/claude.yml 複製到你 repo 的 .github/workflows/。官方說明它是可以直接運作的 workflow,不只是範例:有人在 issue 或 PR 提到 @claude,Claude 就會回應,預設用 ANTHROPIC_API_KEY 認證。如果你加的是 CLAUDE_CODE_OAUTH_TOKEN,把檔案內 anthropic_api_key 那一行改為:
claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
Commit 並 push 之後,在 issue 或 PR 留言 @claude 測試。
第一個 workflow:@claude 回應 issue 同 PR
以下是官方文件列出的最簡版本,照錄原文(以 API key 認證)。它以 interactive mode 執行:workflow 沒有 prompt input,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 }}
用訂閱 token 的話,最後一步改為:
- uses: anthropics/claude-code-action@v1
with:
claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
以下幾行不是樣板,要知道它們的作用:
id-token: write:Action 預設以 Claude GitHub App 認證時需要。actions: read:讓 Claude 讀取 PR 上的 CI 結果。actions/checkout:給 Claude 一份 repo 副本工作。if:留言沒有提到@claude時,不啟動 runner;Action 本身亦會再檢查觸發字。
官方 examples/claude.yml 比這個版本多兩類觸發:新開或被指派的 issue(標題或內容有 @claude),以及提交的 PR review(review 內容有 @claude)。觸發字預設是 @claude,可以用 trigger_phrase input 更改。
留言寫法
@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 留言回覆,並在工作期間更新該留言。官方的成本建議之一,是把 @claude 要求寫得具體,讓 Claude 用較少回合完成。以下是本站自擬的寫法示例,不是實際輸出:
[本站示例] @claude 按 issue 描述修正訂單總額的四捨五入問題:只改 src/billing/,補一個單元測試,唔好改 API 回應格式。
留意:在 issue 和 PR 事件,留言的人必須對 repo 有 write 權限,Claude 才會執行;bot 觸發亦一律拒絕,除非列入 allowed_bots,以免 bot 互相觸發形成循環。

PR 自動審查 workflow
想每個 PR 開啟或更新時都自動審查,官方示例用 code-review plugin,與快速設定產生的審查 workflow 用同一個 plugin。以下 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"'
- 觸發:PR 開啟(opened)、有新 push(synchronize)、轉為可審查(ready_for_review)和重新開啟(reopened)。
plugin_marketplaces和plugins:安裝code-reviewplugin;prompt執行它的 skill。因為提供了prompt,這個 workflow 以 automation mode 執行,不需要@claude。--comment:Claude 會在 PR 上留下審查:每個問題一條 inline comment,找不到問題就留一條總結留言。沒有這個參數,Claude 不會留言,你只能在 workflow run log 看結果。claude_args那一行:即使 skill 本身已列明同一個工具,也要保留,因為 Action 只會在--allowedTools列明時,才啟動貼 inline comment 的 MCP server。- 用訂閱 token:同樣把
anthropic_api_key一行換成claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}。
哪些 PR 會被略過:draft 和已關閉的 PR、Claude 判斷不需要審查的 PR(例如自動產生或很瑣碎的改動),以及已經有 Claude 留言的 PR。
Fork 開出的 PR:在公開 repo,GitHub 不會把 Secret(GITHUB_TOKEN 除外)傳給由 fork 觸發的 workflow,所以審查只會在同一 repo 的 branch 開出的 PR 執行。
舊版審查 workflow 只寫 log:Claude Code v2.1.229 之前,由 /install-github-app 產生的審查 workflow 只把結果寫進 workflow run log。兩個更新方法:再執行 /install-github-app,當 repo 已有 claude.yml 時揀 Update workflow file with latest version,Claude Code 會把最新檔案 push 到新 branch 並開 PR;或者自己在已提交的檔案加上 --comment 參數和上面的 claude_args 一行,保留你做過的其他修改。
審查準則寫在 CLAUDE.md:官方建議在 repo 根目錄的 CLAUDE.md 寫下程式碼風格、審查準則和項目規則,Claude 建立 PR 和回應要求時都會跟從;但每次執行都會讀它,所以要保持精簡。CLAUDE.md 的寫法見 Claude Code 新手教學。無論 Claude 有沒有留言,官方的保安建議都是 merge 前先審查 Claude 的改動;本站建議原有的測試和人手 review 照舊保留,Claude 的審查只作額外一層。

issue 變 PR:Claude 會做乜、唔會做乜
根據官方 claude-code-action 保安文件和能力與限制文件:
- 在 issue 觸發:一定開新 branch 工作。
- 在開啟中的 PR 觸發:直接 push 到該 PR 的 branch;在已關閉的 PR 觸發,則開新 branch。
- 預設不會自己開 PR:回應
@claude時,Claude 把改動 commit 到新 branch,在回覆中附上 GitHub 建立 PR 頁面的連結,由你按連結自己建立 PR,確保合併前有人把關。 - 不能 approve PR:官方表示這是基於保安理由。
- 只做 push commit:不會 merge、rebase,亦不做 push commit 以外的 git 操作。
- 預設不能執行任意 Bash 指令:要明確允許,例如在
claude_args用--allowedTools列出,官方examples/claude.yml的註解就以Bash(npm run test:*)等指令為例。
如果你想把 issue 交給 Claude 處理,最實際的流程是:在 issue 寫清楚要求和驗收條件,留言 @claude,等它 push 好 branch,按連結建立 PR,然後照你平時的流程審查和測試。
排程同自動化模式
Workflow 有沒有提供 prompt input,決定 Action 用哪種模式:
| 模式 | 條件 | 何時執行 | 結果出現在哪裡 |
|---|---|---|---|
| Interactive mode | 沒有 prompt | 等 @claude 出現在 issue/PR 留言、PR review,或新 issue 的標題或內容 | 觸發的 issue 或 PR 留言 |
| Automation mode | 有 prompt | 毋須提到 @claude,按 workflow 事件執行,包括 cron 排程;仍受觸發者檢查 | 預設在 workflow run log;prompt 有要求而 Claude 有可用工具時,才可以留言 |
- Prompt 可以是 skill:repo 內
.claude/skills/的 skill,要先執行actions/checkout,再以/skill-name作 prompt;plugin 內的 skill 則用/plugin-name:skill-name。 - 純文字 prompt 預設沒有工具:沒有 shell 或 GitHub API 存取權,要用
claude_args的--allowedTools,或settingsinput 的permissions.allow規則,授予需要的工具。 - 排程只在預設 branch 執行:GitHub 只會從預設 branch 執行排程 workflow;公開 repo 如果 60 日沒有活動,GitHub 會停用排程。
- 排程亦受 bot 檢查:GitHub 會把排程 run 歸於一位 repo 使用者,通常是最後修改
cron的人;如果那是 bot,要把它列入allowed_bots。
成本:GitHub 分鐘加 token 或訂閱用量
官方說明每次執行消耗兩種資源:GitHub Actions 分鐘,以及 Claude 的 token;用訂閱 token 時,則用你的 Claude 訂閱。
GitHub Actions 分鐘
| GitHub 帳戶 | 私人 repo 每月內含分鐘 |
|---|---|
| GitHub Free | 2,000 |
| GitHub Free for organizations | 2,000 |
| GitHub Pro | 3,000 |
| GitHub Team | 3,000 |
根據 GitHub Actions 官方計費文件(2026-09-15 核對,美元):公開 repo 使用標準 GitHub-hosted runner 是免費的;私人 repo 用完內含分鐘後,按 runner 計費,例如 Linux 2-core 每分鐘 US$0.006、Windows 2-core US$0.010、macOS US$0.062。分鐘計入 repo 擁有者,而不是觸發 workflow 的人。本文所有官方範例都用 ubuntu-latest(Linux)。
本站計算(只作舉例):假設 GitHub Free 帳戶的私人 repo,某月用了 2,500 分鐘 Linux 2-core runner,超出內含的 2,000 分鐘共 500 分鐘,500 × US$0.006 = US$3。這只計 GitHub 分鐘,不包括 Claude 的 token 或訂閱費用。
API key:按 token 計費
| 模型 | 輸入(每百萬 token) | 輸出(每百萬 token) |
|---|---|---|
| Claude Sonnet 5 | US$2 | US$10 |
| Claude Opus 5 | US$5 | US$25 |
來源:Claude API 官方價格頁(所有價格為美元,2026-09-15 核對)。Sonnet 5 的 US$2/US$10 原本是推出時的優惠價,官方現已定為標準價,原定 2026 年 9 月 1 日加至 US$3/US$15 的調整不會實施。每次互動用多少 token,取決於 prompt 和回應長度、任務複雜度和 codebase 大小,官方沒有「每次執行」的固定數字,本文亦不作估算。不寫 --model 時,Action 用 Claude Code 的預設模型。
訂閱 token:用你的訂閱用量
用 CLAUDE_CODE_OAUTH_TOKEN 時,執行用你的 Claude 訂閱,而 Pro 和 Max 的用量限制由 Claude 和 Claude Code 共用。官方的 Claude Code 成本文件亦指出,每位開發者的成本差異很大,視乎模型選擇、codebase 大小,以及同時跑多個 instance 或自動化等用法。用量機制和減少浪費的方法,請看 Claude Pro、Max 與 Claude Code 用量限制。
官方的控制成本方法
- 把
@claude要求寫具體,讓 Claude 用較少回合完成。 - 用 issue template 預先提供 context。
- CLAUDE.md 保持精簡,因為每次執行都會讀取。
- 在
claude_args設定--max-turns,限制回合數。 - 設定 workflow 層面的 timeout,避免失控的 job。
- 用 GitHub 的 concurrency 控制,限制同時執行的數量。
claude_args: "--max-turns 5 --model claude-sonnet-5 --mcp-config /path/to/config.json"
上面一行照錄官方文件:--max-turns 限制回合,--model 指定模型,--mcp-config 指向 MCP 設定檔(MCP 的用法見 Claude Code MCP 教學)。想先估算每月整體 AI 訂閱開支,可以用本站的 AI 訂閱成本計算器。
安全設定清單
Claude GitHub App 會拿到的權限
Claude GitHub App 由所有與 GitHub 整合的 Claude 功能共用,包括本文的 Action、託管的 Code Review,以及 Claude Code on the web 的 PR auto-fix。GitHub App 只有一套權限,所以安裝時你會授予以下全部權限,當中有些 Action 本身用不到:
| 權限 | 存取 |
|---|---|
| Actions | Read and write |
| Checks | Read and write |
| Contents | Read and write |
| Discussions | Read and write |
| Issues | Read and write |
| Members | Read |
| Metadata | Read |
| Pull requests | Read and write |
| Repository hooks | Read and write |
| Statuses | Read |
| Workflows | Read and write |
以上照錄 官方文件的權限表(2026-09-15 核對)。GitHub 不容許只接受部分權限;當 App 日後要求新權限,GitHub 會請帳戶擁有者(organization 則是 organization owner)批准,未批准前沿用舊權限。如果機構只容許 Action 實際用到的權限,官方建議自行建立只有 Contents、Issues 和 Pull requests 的 custom GitHub App;不過 custom app 只適用於 Action,託管 Code Review 和 web auto-fix 仍然要用官方 App。
逐項檢查
- 憑證只放 Secret:官方警告,永遠不要把 API key 或 OAuth token 直接 commit 到 repo,一律存成 GitHub Secret 再在 workflow 引用。
- 最少權限:只給 workflow 需要的權限,並在 merge 前審查 Claude 的改動。
- 小心隱藏指令(prompt injection):外部貢獻者可能透過 HTML 註解、隱形字元、隱藏屬性等方式,在 issue 或 PR 內夾帶給 Claude 的指令。Action 會移除 HTML 註解、隱形字元、markdown 圖片 alt text、隱藏 HTML 屬性和 HTML entities,但官方提醒仍可能出現新的繞過手法,建議先檢查外部貢獻者輸入的原始內容,才讓 Claude 處理。
allowed_non_write_users屬高風險:官方把它標為 RISKY,它會繞過 write 權限要求,只應用於權限極有限的 workflow,例如只有issues: write的 issue 標籤 workflow。- 不要先 checkout 不可信的 ref:官方寫明,不要在執行 Action 之前,把不可信的 ref checkout 到 workspace 根目錄。
- 公開 repo 的 log 人人看得到:公開 repo 的 GitHub Actions log 是公開的,所以 Action 預設不顯示 Claude 的完整輸出,開啟前要三思。如需截圖分享 workflow 畫面,先遮蓋帳戶名稱、organization、電郵和任何 token。
- 刪 Secret 不等於撤銷憑證:官方說明刪除 Secret 後,憑證本身仍然有效;要完全停用 API key,要在 Claude Console 一併刪除。訂閱 token 則不同:截至 2026-09-15,官方的認證文件和 Actions 文件都沒有列出提早撤銷
claude setup-tokentoken 的步驟,換言之它一發出就有效一年。這也是團隊共用的 Secret 應該用 API key 或 workload identity federation 的另一個理由;訂閱 token 一開始就只應放在自己 repo 的 Secret。 - 自動修 CI 的範例要限用:官方的 CI 自動修復範例 workflow 註明,只應在所有具 write 權限的人都完全可信的 repo 使用。
帳戶本身的保安,例如密碼、多重驗證和登入裝置,可以用本站的 AI 帳戶安全檢查表逐項核對。
常見錯誤同排解
| 現象 | 可能原因 | 處理方法 |
|---|---|---|
留言 @claude 後沒有反應 | App 未安裝、workflow 未啟用、Secret 未設定、觸發字寫錯,或留言者沒有 write 權限 | 逐項確認:Claude GitHub App 已安裝在該 repo;repo 已啟用 workflow;Secret 已設定;留言中的 @claude 是完整一個字(不是 /claude 或 @claude-bot);留言者有 write 權限 |
| Claude push 的 commit 沒有觸發 CI | GitHub 不會因為以預設 GITHUB_TOKEN 做的 commit 觸發 workflow | 如果你在 Action 傳入 github_token: ${{ secrets.GITHUB_TOKEN }},刪除它,讓 Action 以 Claude GitHub App 認證,或改傳 custom app token;並確認 CI 的觸發事件包括 push 或 pull_request |
認證錯誤,例如 OAuth token revoked 或 401 OAuth token has expired | CLAUDE_CODE_OAUTH_TOKEN 已過期(有效期一年)或被撤銷;或 key/token 本身無效 | 先在本機用 claude 測試憑證是否有效;token 過期就再執行 claude setup-token,把新 token 更新到 repo Secret |
| 審查結果只在 run log,PR 上沒有留言 | v2.1.229 之前產生的審查 workflow,或 prompt 沒有 --comment | 再執行 /install-github-app 揀 Update workflow file with latest version,或自己加上 --comment 和 claude_args 一行 |
| Fork 開出的 PR 沒有自動審查 | 公開 repo 中,GitHub 不會把 Secret 傳給由 fork 觸發的 workflow | 屬 GitHub 的預設保安設計;審查只會在同一 repo 的 branch 開出的 PR 執行 |
| Run 因觸發者是 bot 而失敗 | Action 預設拒絕 bot 觸發,排程 run 亦會檢查 | 確認該 bot 需要觸發 Claude 後,才把它列入 allowed_bots |
| 排程 workflow 停了 | 公開 repo 60 日沒有活動,GitHub 停用排程;或 workflow 不在預設 branch | 把 workflow 放在預設 branch,並在 repo 的 Actions 頁重新啟用排程 |
/install-github-app 顯示通知後退出 | repo 的 remote 在 gitlab.com 或 bitbucket.org | 這個指令只支援 github.com;GitLab 請看官方的 Claude Code GitLab CI/CD 文件 |
| 用了訂閱,卻被收 API 費用 | 快速設定時沿用了本機已有的 API key,Secret 其實是 ANTHROPIC_API_KEY | 檢查 repo Secret 名稱和 workflow 的 input;要用訂閱就改用 CLAUDE_CODE_OAUTH_TOKEN 和 claude_code_oauth_token |
| 帳戶本身因所在地區未受支援而無法開通或使用 | 所在地不在 Anthropic 官方支援國家/地區名單內(見文首方格) | 這是帳戶資格問題,不是 workflow 設定錯誤,改 workflow 或 Secret 都不會改變它。本文不提供任何繞過方法,請看 Claude 香港訂閱指南 |
舊教學用 @beta?這樣改到 v1
如果你參考的教學或舊 workflow 仍然寫 anthropics/claude-code-action@beta、direct_prompt 或 mode,官方的升級步驟是:
- 把
uses一行的@beta改為@v1。 - 刪除
modeinput,現在 Action 會自動判斷模式。 - 把
direct_prompt改為prompt。 - 把
max_turns、model等 CLI 選項搬進claude_args;custom_instructions沒有同名參數,改用--append-system-prompt。
解除安裝
- Workflow 檔案:刪除
.github/workflows/內使用anthropics/claude-code-action的檔案;用快速設定的話,找claude.yml,以及(如有揀)claude-code-review.yml。刪除後 Action 便不會再執行。 - Secret:刪除 repo 內的
ANTHROPIC_API_KEY或CLAUDE_CODE_OAUTH_TOKEN;如果放在 organization 層面,亦要一併刪除。記住刪除 Secret 不會令憑證失效,API key 要在 Claude Console 刪除。 - GitHub App:在 repo 或 organization 設定的 GitHub Apps 解除安裝 Claude GitHub App,但只限你沒有用它做其他 Claude 功能(例如 Code Review 或 web auto-fix)的情況。
下一步
- 未裝 Claude Code:先看 Claude Code 安裝教學。
- 仍在揀方案:看 Claude Code 要用邊個 Claude 方案。
- 想了解第三方 API 中轉:看 Claude Code API 中轉風險。
- 用 Codex 做 code review:看 Codex 自動 code review 教學。
- 寫好 CLAUDE.md:看 Claude Code 新手教學。
本站的 Claude Code 方案服務頁列明服務內容和條款,頁面價錢是本站獨立服務價,並非 Anthropic 官方價格。本站與 OpenAI/Anthropic 並無從屬關係;付款前請閱讀服務條款。
結論
Claude Code GitHub Actions 的設定其實只有三件事:Claude GitHub App、一個 Secret、一個 workflow,用 /install-github-app 幾分鐘就可以完成。真正要想清楚的是憑證:個人在自己的 repo 可以用 claude setup-token 產生的訂閱 token,團隊共用就用 API key 或 workload identity federation,並且永遠不把 token 交給別人。之後先用 @claude 在幾個 issue 和 PR 試用,再加上帶 --comment 的審查 workflow,並用 --max-turns 和 timeout 控制成本。至於所在地是否受支援,請以官方名單為準,不要依賴任何繞過方法。
資料來源與引用
我們附上第一手及官方來源,方便你逐一核實。
- 1.Claude Code GitHub Actions — Anthropic (Claude Code Docs)
- 2.Claude Code authentication: generate a long-lived token — Anthropic (Claude Code Docs)
- 3.Code Review — Anthropic (Claude Code Docs)
- 4.Legal and compliance — Anthropic (Claude Code Docs)
- 5.Claude Code error reference — Anthropic (Claude Code Docs)
- 6.Manage Claude Code costs — Anthropic (Claude Code Docs)
- 7.Claude Code setup and system requirements — Anthropic (Claude Code Docs)
- 8.anthropics/claude-code-action — Anthropic (GitHub)
- 9.claude-code-action example workflow (examples/claude.yml) — Anthropic (GitHub)
- 10.claude-code-action security — Anthropic (GitHub)
- 11.claude-code-action capabilities and limitations — Anthropic (GitHub)
- 12.Using secrets in GitHub Actions — GitHub Docs
- 13.GitHub Actions billing — GitHub Docs
- 14.Disable and enable workflows — GitHub Docs
- 15.Claude API pricing — Anthropic (Claude Platform Docs)
- 16.Claude plans and pricing — Anthropic
- 17.What is the Max plan? — Anthropic Support
- 18.Use Claude Code with your Pro or Max plan — Anthropic Support
- 19.Anthropic Consumer Terms — Anthropic
- 20.Anthropic supported countries — Anthropic
常見問題
Claude Pro 可以用 Claude Code GitHub Actions 嗎?
可以。官方文件列明,以 Claude 訂閱認證的 CLAUDE_CODE_OAUTH_TOKEN 適用於 Pro、Max、Team 和 Enterprise 方案:在本機執行 claude setup-token 產生,存成 repo Secret,再在 workflow 用 claude_code_oauth_token 引用。官方說明用 OAuth token 時,執行會用你的 Claude 訂閱而不是 API 計費;Pro 和 Max 的用量限制由 Claude 和 Claude Code 共用。官方沒有公布每次 workflow 用多少用量。
用 GitHub Actions 一定要 Max 先夠用?
官方沒有公布一次 workflow 會用多少訂閱用量,所以不能一概而論。Max 5x 和 Max 20x 分別提供 Pro 每個 session 5 倍和 20 倍的用量,屬相對倍數,不是固定訊息數或執行次數。可以先用 Pro 或現有方案、在少數 PR 試用,並用 --max-turns、workflow timeout 和 concurrency 控制每次工作量;揀方案請看本站的 Claude Code 方案指南。
團隊可以共用一個人的訂閱 token 嗎?
不應該。官方文件說明 OAuth token 綁定執行 claude setup-token 那個人的訂閱,要在多個 repo 或 organization 共用的 Secret,官方建議改用 Claude Console 的 API key;Anthropic 的法律與合規頁亦說明 Pro、Max 的用量上限以一般、個人使用為前提,而 Consumer Terms 禁止把帳戶登入資料、API key 或帳戶憑證交給其他人。團隊 repo 應用 API key 或 workload identity federation,訂閱 token 只由產生它的人在自己的 repo 使用。
Claude Code GitHub Actions 同 Anthropic 的 Code Review 是否同一樣嘢?
不是。本文的 GitHub Actions 是你自己在 repo 放 workflow 檔案的整合,可以用訂閱 token 或 API key。託管的 Code Review 毋須寫 workflow,但目前是 research preview,只限 Team 和 Enterprise,開啟 Zero Data Retention 的機構不可用;每次審查平均 US$15–25,經 usage credits 另行計費,不計入方案內含用量。其他方案可以在本機用 /code-review 審查 diff。
公開 repo 用 Claude Code GitHub Actions 會唔會用 GitHub Actions 分鐘?
GitHub 官方計費文件說明,公開 repo 使用標準 GitHub-hosted runner 是免費的;私人 repo 每月有內含分鐘(GitHub Free 2,000 分鐘,GitHub Pro 和 GitHub Team 3,000 分鐘),超出後按 runner 收費,例如 Linux 2-core 每分鐘 US$0.006,並計入 repo 擁有者。Claude 的 token(或訂閱用量)另外計算。另外要留意,公開 repo 由 fork 開出的 PR 拿不到 Secret,審查 workflow 只會在同一 repo 的 branch 執行。
Claude 會唔會自己 merge 或 approve PR?
不會。官方 claude-code-action 文件列明 Claude 基於保安理由不能 approve PR,亦不會 merge、rebase 或做 push commit 以外的 git 操作。回應 @claude 時,預設做法是把改動 commit 到新 branch,並附上建立 PR 的連結,由你自己建立 PR;在開啟中的 PR 觸發時,則直接 push 到該 PR 的 branch。官方建議 merge 前先審查 Claude 的改動。
setup-token 產生的 token 過期會點?
claude setup-token 產生的 token 有效期一年,只在終端機顯示一次,Claude Code 不會替你儲存。token 過期或被撤銷時,會出現與登入失效相同的認證錯誤,例如 OAuth token revoked 或 401 OAuth token has expired。官方做法是再執行 claude setup-token 產生新 token,然後更新 repo 的 CLAUDE_CODE_OAUTH_TOKEN Secret;除錯前可先在本機用 claude 測試 token 是否有效。建議產生 token 時就在日曆記下一年後的日期。
香港可以用 Claude Code GitHub Actions 嗎?
截至 2026 年 9 月 15 日,香港並不在 Anthropic 官方支援國家/地區名單內,該名單同時涵蓋 Commercial API 及 Claude.ai。Claude Code GitHub Actions 無論用訂閱 token 還是 API key,都是使用 Anthropic 的服務,同樣受這份名單規限。本文不提供任何繞過地區限制的方法;請先閱讀本站的 Claude 香港訂閱指南,並留意官方名單更新。
本文遵循我們的 編輯準則.

關於作者
HK Learn AI 編輯部
HK Learn AI 編輯部負責研究、查證同編寫每一篇內容,並引用官方及第一手來源。
此主題相關文章

Jev Choice、Score、Noul 教學:選項、評級與是非機率點樣設計
以客服和故障評級例子拆解 Choice、Score、Noul:選項覆蓋、rubric、加權分數、否定句與批次獨立性,避免輸出可解析卻語意錯誤。

Jev API 教學:用 JavaScript 發出第一個 TypeSafe 請求、讀取答案與處理錯誤
用 Node.js 與 fetch 呼叫 Jev:完整 model/state/questions 示例,讀取 Choice、Noul 和 usage,處理 401、422、429、529,並固定模型版本。

Claude Code MCP 教學:連接 GitHub、資料庫同 Notion,scope、權限同安全設定
按 Anthropic 現行官方文件(2026 年 9 月 15 日核對)一步步設定 Claude Code MCP:加第一個免登入 server、分清 HTTP/stdio 同 -- 分隔符、揀 local/project/user scope,再連接 GitHub(唯讀網址)、DBHub 資料庫(唯讀帳戶)同 Notion,最後講 mcp__ 權限規則、安全清單、context 用量同常見錯誤。文首附支援地區狀態。