跳到主要內容
技術

Claude Code GitHub App：安裝、整合與自動觸發教學

完整教學：如何安裝 Claude Code 的 GitHub App、設定 PR / Issue 事件觸發，讓 Claude 自動審查程式、修復 Bug、甚至直接送出 commit。

Claude Code GitHub AI 開發工具 自動化

GitHub 上的開發流程多半長這樣：發現 bug → 開 issue → 有人接手 → 修好 → PR → review → merge。每一步都要人介入，整體很慢。

Claude Code GitHub App 把其中幾步交給 Claude。你在 issue 或 PR 留言裡 @claude 一聲，它會自己讀程式、寫修補、開 PR。本文說明怎麼裝、怎麼設定、怎麼觸發，順便把幾個常被搞混的細節講清楚。

三個元件先分清楚

很多人把「GitHub App」和「GitHub Action」混為一談。這個整合其實是三個元件配合：

  • Claude GitHub App：負責認證與權限。代表 Claude 在你 repo 裡的身份。
  • anthropics/claude-code-action@v1：實際在 GitHub Actions runner 上跑 Claude 的 action。
  • Workflow 檔（.github/workflows/claude.yml）：把上面兩者串起來，定義什麼事件會觸發 Claude。

@claude 之所以會有反應，是因為某個 workflow 監聽到 issue_comment 事件，用 App 的權限呼叫 action 去跑 Claude。三個缺一不可。

好在底下的 /install-github-app 指令會一次幫你建好這三樣。

安裝

兩種安裝方式：

  • 快速安裝：在 Claude Code 內跑 /install-github-app。Anthropic API 用戶（console.anthropic.com，按 token 計費）與 Claude Pro / Max 訂閱用戶都能用——CLI 會偵測你目前的登入身分，自動把對應的 secret 寫進 repo。
  • 手動安裝：fallback，適用於 /install-github-app 失敗、想用 claude setup-token 拿壽命較長的 OAuth token（Pro / Max 用戶常見需求），或單純想自己掌控每一步的人。

兩種方式都需要你是該 repo 的 admin，以及本機已安裝並登入 Claude Code。

Bedrock / Vertex AI 用戶另有專屬流程，本文不涵蓋，請見官方文件。

快速安裝：/install-github-app

打開 terminal，進入該 repo 目錄，啟動 Claude Code：

claude

在 prompt 裡輸入：

/install-github-app

這個指令會引導你完成三件事：

  1. 把 Claude GitHub App 安裝到指定的 repo
  2. 加 secret 到 repo 的 GitHub Actions：
    • API 用戶：寫入 ANTHROPIC_API_KEY
    • Pro / Max 用戶：寫入 CLAUDE_CODE_OAUTH_TOKEN（從你目前 CLI 的登入 session 抽出來的 OAuth token）
  3. 對你的 repo 自動開一個 PR，加入兩個 workflow 檔：
    • .github/workflows/claude.yml：處理 @claude 觸發
    • .github/workflows/claude-code-review.yml：每次開 PR 自動 review

Merge 那個 PR，@claude 就能用了。

Pro / Max 用戶注意：/install-github-app 寫入的 OAuth token 壽命可能很短（社群回報過 ~1 小時即失效，無 auto-refresh，見 issue #11016）。如果遇到 workflow 沒幾天就壞掉，改走下面的「手動安裝」用 claude setup-token，產生有效期一年的 token。

手動安裝

如果 /install-github-app 失敗、Pro / Max 用戶想要壽命較長的 OAuth token，或你想完全掌控每一步：

  • Pro / Max 用戶：照下列步驟原樣執行。
  • API 用戶：流程相同，但第 2 步改用你的 API key，第 3 步 secret 改名 ANTHROPIC_API_KEY，第 4 步 workflow 改用 anthropic_api_key 參數。

  1. 到 https://github.com/apps/claude 點 Install，選擇要安裝的 repo。App 會請求 Contents、Issues、Pull requests 三項的 Read & Write 權限。

  2. 在 terminal 跑 claude setup-token，依提示完成 OAuth 授權，複製輸出的 token。

  3. 在 repo 的 Settings → Secrets and variables → Actions 新增 secret：名稱 CLAUDE_CODE_OAUTH_TOKEN，值是剛才複製的 token。

  4. 手動建立 .github/workflows/claude.yml，用 claude_code_oauth_token 參數（不是 anthropic_api_key）：

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

claude setup-token 產生的 token 有效期一年，只用於 inference，到期前跑一次 claude setup-token 更新即可。

設定 CLAUDE.md

App 裝好之後，建議在 repo 根目錄放一份 CLAUDE.md，把專案規範寫進去。Claude 執行任務前會讀它，當作工作守則。

範例：

# CLAUDE.md

## 專案說明

用 Astro + Tailwind 建立的靜態部落格，部署在 Cloudflare Pages。

## 開發指令

- npm run dev：啟動開發伺服器
- npm run build：建置

## 注意事項

- 所有文章放在 src/content/blog/，格式為 Markdown
- 不要修改 tailwind.config.mjs 裡的 color token
- PR 標題請用中文

寫得越具體，Claude 越不會自由發揮。如果有「絕對不能碰的檔案」、「特定 commit 訊息格式」這類硬規定，直接列出來。

觸發 Claude 執行任務

裝完之後可以這樣用。先記住一件事：預設 workflow 只監聽留言（issue_comment 與 pull_request_review_comment），不監聽 issue body。要讓 issue body 也觸發 Claude，得改 workflow，下一節會講。

在 Issue 留言裡指派任務

開一個 issue，描述清楚問題，然後在留言區用 @claude：

@claude 請幫我修復這個 bug：當使用者點擊深色模式切換按鈕時，
頁面會短暫閃爍白色背景，應該要無縫切換。

Claude 會讀 issue 上下文與相關程式碼，定位問題，建立新 branch，commit 修補，最後開一個 PR。

在 PR 留言裡請 Claude review

@claude 請 review 這個 PR，特別注意是否有效能問題或安全漏洞。

Claude 會逐檔分析 diff，在對應行號留下 review 意見。

在 PR 留言裡請 Claude 修改

@claude 請把這個 PR 裡所有的 var 改成 const 或 let，
並確保沒有破壞現有邏輯。

Claude 會直接 push 新 commit 到同一個 branch。

給長任務的 issue

複雜功能可以開一個比較完整的 issue，但記得 @claude 要寫在留言而不是 body：

issue 內文：

實作 RSS feed 功能。

需求：
- 路徑：/rss.xml
- 包含所有非 draft 的文章
- 欄位：title, link, description, pubDate
- 使用 @astrojs/rss 套件

請先閱讀 src/pages/ 下的現有頁面結構，再決定實作方式。

開完 issue 後留一則 comment：@claude 開工。

如果不想多留一則 comment，直接編輯 .github/workflows/claude.yml，加上 issues 事件觸發（下一節有範例）。

自訂 workflow

/install-github-app 已經幫你裝好兩個 workflow，大多數情況夠用。如果預設行為不符合需求，直接編輯對應的 yml 檔調整。

讓 issue body 也能觸發

加上 issues 事件，並用 if 過濾，避免每次開 issue 都跑 Claude：

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

jobs:
  claude:
    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:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

每次開 PR 自動 review（不需要 @claude）

直接給 prompt 參數，action 會自動進入「automation 模式」：

name: Claude Auto 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 }}
          prompt: "Review this pull request for code quality, correctness, and security. Analyze the diff, then post your findings as review comments."
          claude_args: "--max-turns 5"

claude_args 可以塞任何 Claude Code CLI 參數，例如 --model claude-opus-4-7、--allowedTools "Read,Bash"。

權限與安全

App 預設權限

權限說明
Contents（Read & Write）讀寫 repo 檔案、建立 branch、commit
Issues（Read & Write）讀 issue、留言
Pull requests（Read & Write）讀 PR、開 PR、留 review

不想讓 Claude 直接 push 到主線，用 GitHub 的 branch protection 擋，比寫進 CLAUDE.md 可靠。CLAUDE.md 是工作守則，沒有強制力。

啟用 Branch Protection

在 GitHub repo 的 Settings → Branches 對 main 加保護：

  • Require a pull request before merging
  • Require approvals（至少 1 人）

這樣即使 Claude 有 Write 權限也無法繞過 review，所有變更都得經過你按 merge。

API key 不要寫死在 workflow

只能用 ${{ secrets.ANTHROPIC_API_KEY }} 引用，永遠不要把 key 直接貼進 YAML。

一個完整流程的樣子

1. 你開一個 issue

標題：導覽列在手機上點擊後沒有收合

問題描述：
viewport < 768px 時，點擊漢堡選單展開導覽列後，
點任一連結雖然會跳頁，但選單沒收合，蓋住整個畫面。

相關檔案：src/components/Navbar.astro

2. 你在 issue 底下留言

@claude 請幫我修復這個問題。

3. Claude 開工

幾分鐘後，Claude 會在 issue 底下留言它的分析與計畫，建立新 branch，把改好的 commit 推上去，然後開 PR：

fix: 修復手機版導覽列點擊連結後未收合的問題

在 Navbar.astro 加入點擊事件監聽，當使用者點擊導覽連結時
移除 open class 以收合選單。

Closes #42

4. 你 review 後 merge

看一下 diff、確認沒問題就 merge。完成。

常見問題

Q：留言了 @claude 但沒反應，怎麼辦？

依序檢查：

  1. GitHub App 是不是裝在這個 repo（Settings → Integrations → GitHub Apps）
  2. ANTHROPIC_API_KEY 是不是設在這個 repo 的 secret
  3. .github/workflows/claude.yml 有沒有 commit 進 main
  4. Actions 分頁裡有沒有對應的 workflow run，run 失敗的話看 log

Q：寫 /claude 而不是 @claude 也行嗎？

不行，必須用 @claude。觸發判斷是 GitHub Actions 的 workflow 在做的，看的是字串 @claude。

Q：Claude 做出來的東西不符合預期？

把規則寫進 CLAUDE.md，越具體越好。或在 issue 留言裡給更明確的指令，例如「只修改 src/components/ 下的檔案」。

Q：Private repo 也能用嗎？

可以。安裝時選 private repo 即可。程式碼不會離開 GitHub 的 runner，除了送給 Anthropic API 的部分。

Q：我是 Claude Pro / Max 訂閱用戶，要怎麼取得 ANTHROPIC_API_KEY？

不需要 API key。Pro / Max 用戶用 OAuth token 即可：

  • 跑 /install-github-app 最簡單，CLI 會自動把 OAuth token 寫進 repo secret——但 token 可能短期過期。
  • 想要一年期的長壽命 token，跑 claude setup-token 手動產生，存到 repo secret 叫 CLAUDE_CODE_OAUTH_TOKEN，workflow 裡用 claude_code_oauth_token 參數引用。詳細步驟在安裝章節的「手動安裝」。

Q：費用怎麼算？

兩塊：GitHub Actions 跑 runner 的時間（吃你的 Actions 額度），加上 Claude API 的 token 費用（吃你的 Anthropic 額度）。長任務或多個並行 workflow 都會貴。可以用 claude_args: "--max-turns 5" 之類限制每次的呼叫上限。

結語

核心三步：

  1. 跑 /install-github-app 安裝 GitHub App（API、Pro / Max 用戶皆可）
  2. 在 repo 根目錄寫 CLAUDE.md
  3. 在 issue 或 PR 留言裡 @claude

裝好之後，把 @claude 當成你的第一個指派對象。Bug 修復、小功能、code review 這類事可以直接丟給它，腦力留給真正需要判斷的事。