Claude GitHub App 怎麼裝？從 /install-github-app、權限到 @claude 排查完整指南（2026）

最後更新：2026-04-04

先說結論：Claude GitHub app 要怎麼裝才會真的動？

最短答案是：

你不是只要裝一個 GitHub app，而是要把下面 3 件事一起接好：

所以如果你現在遇到的是：

• @claude 沒反應
• /install-github-app 卡住
• workflow 在，但 comment 沒觸發

通常不是 Claude 壞了，而是這三段鏈路有一段沒接好。

如果你想看更完整的 GitHub 協作工作流，主文在這裡：Claude Code GitHub Actions 教學：怎麼讓 @claude 幫你處理 issue 和 PR（2026）。
如果你現在還沒把 Claude Code 本機權限設穩，也一起看 Claude Code 權限怎麼設？permission modes、allowlist 與安全設定完整整理（2026）。

Claude GitHub app 和 GitHub Actions 差在哪？

很多人把這兩個東西混在一起。

比較準的理解是：

• GitHub app 是 repo 權限與整合層
• GitHub Actions 是執行層

你可以把它想成：

① GitHub app 先幫 Claude 拿到門禁卡
② workflow 再決定它什麼時候進場做事

所以你今天不是在選「裝 app」還是「寫 workflow」。

你是要先把 app 裝上，然後再讓 workflow 去叫它做事。

/install-github-app 什麼時候可以直接用？

依目前官方文件，這條 quick setup 最適合這種情況：

• 你是 repo admin
• 你是 direct Claude API user
• 你想要最快把 GitHub app、secret、workflow 拉起來

官方推薦的做法，是直接在 Claude Code terminal 裡跑：

/install-github-app

它的好處是快。

因為它不是只做一件事，而是會一路引導你把：

• Claude GitHub app
• 必要 secret
• workflow 骨架

一起接起來。

但如果你是走 AWS Bedrock 或 Google Vertex AI，這條 quick setup 就不是主路。這種情況比較穩的做法，是直接走手動安裝。

手動安裝 Claude GitHub app 的順序

如果 /install-github-app 失敗，或你本來就想自己控細節，我會建議按這個順序做：

1. 安裝 Claude GitHub app 到正確的 repo
2. 建立 ANTHROPIC_API_KEY repository secret
3. 在 .github/workflows/ 放進 Claude Code action workflow
4. 到 issue 或 PR comment 實測一次 @claude

這個順序很重要。

因為很多人會先去改 YAML，改半天才發現 app 根本還沒裝，或者 secret 根本不存在。

Claude GitHub app 需要哪些 repo 權限？

依官方文件，目前至少要確認這幾個 repository permissions：

• Contents: Read & write
• Issues: Read & write
• Pull requests: Read & write

如果你是個人 repo，這通常只是流程問題。

但如果你是團隊 repo，這就不是小事。

因為這代表 Claude 不只是會回留言，它是真的能：

• 讀 code
• 改 code
• 推 PR
• 回 issue

所以裝之前，最好先把規則講清楚，不要讓團隊以為它只是個 comment bot。

最小可用的 workflow 長什麼樣？

官方文件的最小骨架大致是這樣：

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

你可以先不要急著魔改。

第一步先確認下面三件事：

• trigger 有沒有進來
• secret 有沒有讀到
• @claude comment 能不能真的把 workflow 叫起來

先把鏈路打通，再去加 prompt、claude_args、schedule，會穩很多。

@claude 沒反應時，最省時間的排查順序

這題不要亂跳著查。

我會直接照這個順序走：

1. 先看 Claude GitHub app 有沒有裝到正確 repo

不是裝到 org 就算完成，也不是你看到 app 名字就算接好了。

先確認：

• 這個 repo 真的在 app 的安裝範圍內
• 不是裝到別的 repo
• 不是只有裝 app，但沒有對應 workflow

2. 再看 .github/workflows/ 裡有沒有 Claude workflow

如果 workflow 不在，GitHub 根本不知道要在 comment 之後做什麼。

這時候你在 issue 裡一直 tag @claude，它也不會自己長出來。

3. 再看 ANTHROPIC_API_KEY secret

這是最常見的第二層問題。

app 裝了、workflow 也在，但 secret 沒設，最後就是 workflow 起來了，Claude 沒法執行。

4. 最後才看 comment 事件和 YAML 細節

像：

• 觸發事件是不是寫對
• action 版本是不是還停在舊 beta
• repo policies 有沒有擋掉 bot 行為

這些要查，但不要第一步就鑽進 YAML。

/install-github-app 失敗，通常是哪 4 類原因？

這張表的重點是：

/install-github-app 失敗，不等於整條線不能用。
很多時候只是代表你該改走手動流程，不要卡在 quick setup。

什麼情況適合把 GitHub app 和本機 Claude Code 分開用？

這也是很多人一開始沒想清楚的。

比較穩的分工通常是：

也就是說，GitHub app 不是拿來取代本機工作流。

它比較像把 Claude 帶進團隊協作入口。

如果你現在連本機權限、allowlist、CLAUDE.md 都還沒整理好，先把本機盤整穩，再把 app 接進 GitHub，通常會少很多噪音。

我會怎麼建議你第一次上線這條線？

如果你今天是第一次裝 Claude GitHub app，我會建議你照這個節奏：

1. 先把本機 Claude Code 工作流走順
2. 先準備一份最基本的 CLAUDE.md
3. 有 admin 權限又是 direct API user，就先試 /install-github-app
4. 如果 quick setup 卡住，不要硬拗，直接切手動安裝
5. 第一個 use case 先做 @claude review，不要一開始就做重功能實作

這樣做的原因很簡單：

你先驗證協作入口有沒有打通，比你一開始就追求全自動，實際太多。

Claude GitHub App 常見問題 FAQ

Claude GitHub app 裝好之後，為什麼 @claude 還是沒反應？

最常見不是 app 壞了，而是 workflow 或 ANTHROPIC_API_KEY secret 沒接好。先查 app、workflow、secret 這三段鏈路，不要先鑽 YAML 細節。

/install-github-app 一定會成功嗎？

不一定。依官方文件，這條 quick setup 比較適合 repo admin 且使用 direct Claude API 的情境。Bedrock 或 Vertex 通常改走手動安裝比較穩。

Claude GitHub app 和 GitHub Actions 是同一個東西嗎？

不是。GitHub app 是權限與 repo 整合層；GitHub Actions workflow 是執行層。要讓 @claude 能動起來，通常兩邊都要到位。

Claude GitHub app 最低需要哪些 repo 權限？

依官方文件，至少要確認 Contents、Issues、Pull requests 這三組都是 Read & write。

我可以只裝 GitHub app，不寫 workflow 嗎？

如果沒有 workflow，GitHub 不知道要在 comment 或 PR 事件之後執行什麼。所以只裝 app，通常還不夠。

結語：GitHub app 真正解決的是「協作入口」，不是安裝成就感

很多人會把這題看成：

「我到底有沒有把 Claude 裝進 GitHub？」

但更實際的問題其實是：

你有沒有把 Claude 接進一條能穩定被團隊使用、被你驗收、被 GitHub 執行的流程。

所以 GitHub app 本身不是終點。

它只是第一張門票。

真正有價值的是：你能不能讓 @claude 在正確的 repo、正確的 workflow、正確的權限邊界裡，真的開始幫你做事。

參考來源

資料最後查核日期：2026-04-04

• Anthropic Docs: Claude Code GitHub Actions
• Anthropic Docs: Identity and Access Management
• Anthropic Docs: Settings