Claude Code GitHub Actions 教學：怎麼讓 @claude 幫你處理 issue 和 PR（2026）

最後更新：2026-04-04

先說結論：Claude Code GitHub Actions 可以拿來做什麼？

最直觀的答案是：

你在 issue 或 PR 留一句 @claude，Claude 就能開始幫你分析、改碼、開 PR、修 bug，前提是你先把 GitHub app、secret 和 workflow 裝好。

這條線最有價值的地方，不是讓你少打一個指令，而是把 Claude Code 從「只在你本機 terminal 工作」延伸到 GitHub 的協作流程裡。

也就是說，你現在有兩種典型工作方式：

• 在本機用 Claude Code 讀 repo、修 bug、看 diff
• 在 GitHub 用 @claude 讓它接手 issue、PR、review 或自動化任務

如果你要一句最短的使用建議，我會這樣說：

• 你要在本機同步工作：用 Claude Code terminal
• 你要把任務交進 GitHub 流程：用 Claude Code GitHub Actions

這不是二選一，而是兩條不同層級的工作流。

如果你還沒把 Claude Code 基本盤走順，先讀 Claude Code 教學與實戰指南：從安裝、指令到專案工作流（2026）。
如果你現在最卡的是權限或 auto mode，請先讀 Claude Code 權限怎麼設？permission modes、allowlist 與安全設定完整整理（2026）。
如果你是在比較「我要留在 Claude Code 還是改用 Cursor」，就接著看 Claude Code vs Cursor：2026 AI Coding Agent 怎麼選。

Claude Code GitHub Actions 和一般 GitHub Actions 差在哪？

先不要把它想成「又一個 YAML workflow」。

它真正有差的地方，是它把 Claude Code 帶進 GitHub runner，讓 Claude 可以在 workflow 裡吃到：

• repo 內容
• issue / PR context
• 你在 comment 裡下的任務
• CLAUDE.md 裡的專案規則

這代表它不是一個單純跑 shell script 的 action，而是把 AI agent 放進 CI/CD 入口。

官方文件目前的定位也很清楚：

• 在 issue / PR comment 裡 @claude
• Claude 可以分析、改動、開 PR、回應
• 也可以用 prompt 直接跑自動化工作流

這條線的核心不是「比較會寫 YAML」，而是「你要不要讓 AI 進到 GitHub 協作層」。

Claude GitHub app 是什麼？和 workflow 不是同一個東西

這是很多人搜 claude github app 時真正卡住的地方。

先講最短答案：

• GitHub app：讓 Claude 取得 repo 裡 Contents / Issues / Pull requests 這些操作權限
• GitHub Actions workflow：讓 GitHub runner 知道什麼時候觸發 Claude、怎麼執行
• ANTHROPIC_API_KEY secret：讓 workflow 裡的 Claude 可以真的呼叫模型

這三個少一個都不行。

很多人會以為：

「我 workflow 已經寫好了，為什麼 @claude 還是沒反應？」

答案通常不是 YAML 寫錯，而是 GitHub app 根本還沒裝，或 repo 權限沒有接上。

所以如果你今天的目標只是：

• 讓 @claude 能在 issue / PR 裡回應
• 讓 Claude 能讀寫 repo
• 把 GitHub app 裝起來，不要卡在第一步

那你也可以直接搭配 Claude GitHub App 怎麼裝？從 /install-github-app、權限到 @claude 排查完整指南（2026） 一起看。那篇比較專門處理 GitHub app 安裝和排查；這篇則是把整個 GitHub Actions 工作流講完整。

什麼情境最適合用 Claude Code GitHub Actions？

很適合的情境

• 你希望在 issue 裡直接請 Claude 實作功能
• 你想在 PR 裡讓 Claude 先做第一輪 review
• 你有固定型任務，想用 workflow 自動跑
• 你想把 CLAUDE.md 裡的專案規則帶進 CI 流程

不太適合的情境

• 你根本還沒整理好 repo 規則
• 你連 CLAUDE.md 都還沒寫
• 你現在連 GitHub Actions 都不熟
• 你要的是本機細緻修 bug，而不是 issue / PR 層協作

如果你的目標是「先在自己電腦前把任務做順」，那主力還是 Claude Code terminal。
如果你的目標是「把任務交到 GitHub，讓團隊都能在同一個入口叫它做事」，那 GitHub Actions 才會有感。

Claude Code GitHub Actions 可以幫你做哪些事？

官方文件列得很清楚，這條 action 的典型用途包括：

• 根據 issue description 實作功能
• 在 PR 上回答技術問題
• 修某個 bug
• 自動 review
• 定期產報告

官方給的 comment 使用例子就很直白：

@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 Code terminal 直接裝

官方文件目前推薦的最快方式，是直接在 Claude Code 裡跑：

/install-github-app

這個 command 會引導你：

• 安裝 Claude GitHub app
• 配好必要 secret
• 建立對應的 workflow

但有兩個限制要先記住：

• 你要是該 repo 的 admin
• 這個 quick setup 是給 direct Claude API users 用的

如果你是走 AWS Bedrock 或 Google Vertex AI，那就要回到手動設定流程。

如果你現在搜的是 claude github app，要注意一件事：

/install-github-app 不是「裝一個 bot 就好」，它做的是整套 quick setup：

• 安裝 Claude GitHub app
• 幫你接必要的 secret
• 幫你把 workflow 骨架拉起來

所以它快，但前提也比較硬。

方式二：手動安裝

如果 /install-github-app 失敗，或你本來就想自己控細節，官方文件的手動流程是：

1. 安裝 Claude GitHub app 到你的 repo
2. 把 ANTHROPIC_API_KEY 加進 GitHub repository secrets
3. 把 workflow 檔放進 .github/workflows/
4. 在 issue 或 PR comment 裡測試 @claude

官方也寫了 GitHub app 需要的 repository permissions：

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

這個權限組合不算小，所以如果你是團隊環境，最好先跟大家講清楚它能做什麼，不要裝了才發現同事以為它只是會回留言的 bot。

/install-github-app 失敗時，先檢查這 4 件事

最基本的 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 }}

最重要的地方有三個：

1. @v1
   代表你用的是正式 GA 版，不是舊的 beta

2. anthropic_api_key
   一定用 GitHub Secrets，不要硬寫進 YAML

3. trigger 事件
   你到底想用 comment 觸發、PR 觸發，還是排程觸發，會直接決定工作流長相

如果你是從 beta 升上來，要注意哪些 breaking changes？

官方文件有特別列出 v1.0 升級重點。這段很容易被忽略，但實務上很重要。

你至少要改這幾件事：

1. @beta 改成 @v1
2. mode 拿掉，現在 auto-detected
3. direct_prompt 改成 prompt
4. max_turns、model、custom_instructions 這類參數改塞進 claude_args

官方給的 before / after 範例很明確：

舊 beta：

- uses: anthropics/claude-code-action@beta
  with:
    mode: "tag"
    direct_prompt: "Review this PR for security issues"
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

GA v1：

- uses: anthropics/claude-code-action@v1
  with:
    prompt: "Review this PR for security issues"
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    claude_args: |
      --max-turns 10
      --model claude-sonnet-4-6

如果你現在看到 repo 裡還有人在用 @beta、direct_prompt，就不要再沿用了。

CLAUDE.md 為什麼在 GitHub Actions 特別重要？

這條線我反而覺得比 YAML 還重要。

因為 Claude Code GitHub Actions 不是只看你的 prompt，它也會看你 repo 裡的 CLAUDE.md。

官方文件建議把這個檔案放在 repo root，用來定義：

• code style
• review criteria
• project-specific rules
• preferred patterns

這件事的實際意義是：

你不要每次在 issue 裡都重講一次「我們不用這個寫法」「我們命名規則是什麼」「測試要先補哪一層」。把這些規則先寫進 CLAUDE.md，Claude 在 GitHub Actions 裡就比較不會每次都像剛到公司的新人。

如果你想先搞懂 CLAUDE.md 在權限、auto mode 和 classifier 判斷裡的角色，建議一起讀 Claude Code 權限怎麼設？permission modes、allowlist 與安全設定完整整理（2026）。

如果你現在還沒有 CLAUDE.md，那我會建議你先不要急著把 GitHub Actions 開很大。先把規則寫出來，再讓 agent 進來。

哪些 GitHub Actions 使用方式最實用？

1. 先從 issue / PR comment 的 @claude 開始

這是最容易上手的方式。

因為它最接近真人協作：

• 你在 issue 下任務
• Claude 回應
• 它分析、提出方案，甚至動手改

這種方式的好處是你有上下文，也比較容易驗收。

2. 再做固定 prompt 的自動化工作流

官方文件也有給排程型範例，例如每天產摘要：

on:
  schedule:
    - cron: "0 9 * * *"

再搭配：

prompt: "Generate a summary of yesterday's commits and open issues"

這種比較像你把 Claude Code 拿來做固定型自動化，而不是即時協作。

3. Review 類任務很適合先用

例如官方文件就有 PR review 用法。

這類任務特別適合拿來測試，因為：

• 比較不會直接碰 production
• 產出容易驗收
• 可以先讓它當第一層 reviewer

你如果一開始就叫它做最重的功能實作，風險和摩擦通常都比較大。

安全和成本，這兩件事不要晚點才想

安全

官方文件反覆強調：

• API key 不要直接 commit
• 一定放 GitHub Secrets
• action permissions 要只給必要範圍
• Claude 的建議不要不看就 merge

這其實都是老話，但 AI 加進來之後更值得再講一次。

因為你現在不是只在跑 shell script，而是在讓一個有修改能力的 agent 進你的 repo workflow。

成本

這條線至少有兩種成本：

1. GitHub-hosted runners 的 minutes
2. Claude token costs

官方文件也有直接給成本優化建議：

• 用更具體的 @claude 指令，減少不必要呼叫
• 在 claude_args 設 --max-turns
• 設 workflow timeout
• 用 GitHub concurrency controls 限制平行執行

如果你是小團隊，這幾個設定要一開始就想，不然你會很快進入「它很好用，但為什麼帳單開始長」的狀態。

Claude Code GitHub Actions 最常見的 5 個卡點

1. @claude 沒反應

先看 3 件事：

• GitHub app 裝了沒
• workflow 檔在不在 .github/workflows/
• ANTHROPIC_API_KEY secret 有沒有設

這通常不是 Claude 壞了，而是 GitHub 這條鏈某個地方沒接上。

如果你現在卡的其實是「GitHub app 到底裝好沒」，最快的排查路線通常是：

1. 先確認 repo 裡真的看得到 Claude GitHub app
2. 再確認 .github/workflows/ 裡有對應 workflow
3. 最後才去看 comment 觸發與 secret

2. 升級 v1 後 workflow 壞掉

多半是因為你還在沿用 beta 欄位，像：

• mode
• direct_prompt
• custom_instructions

先照官方 migration 方式改成 prompt 和 claude_args

3. Claude 有回，但 CI 不在它的 commit 上跑

這是官方 troubleshooting 也有列的情境。
如果你 workflow 對 bot commit 的處理規則不完整，就會出現 Claude 明明動了，但後續 job 沒跟上的情況。

4. PR review 很空泛

通常不是模型不行，而是你沒給它足夠的 repo 規則。

這時候先回去補：

• CLAUDE.md
• 具體 review prompt
• --max-turns

不要每次都怪 AI 太空。

5. 以為 GitHub Actions 可以取代本機 Claude Code

這是定位錯誤。

GitHub Actions 很適合：

• 協作入口
• review
• issue / PR automation

但如果你要的是：

• 深入本機環境
• 跑你電腦上的 dev server
• 接本機 MCP
• 看真實 terminal 狀態

主場還是本機 Claude Code。

如果你要的是手機接手本機工作，不是 GitHub 協作流程，就改看 Claude Code Remote Control 教學：怎麼從手機延續本機 session（2026）。
如果你要的是聊天入口和權限轉發，則是 Claude Code Telegram 教學：用官方 Channels 從手機操作本機專案（2026）。

我會怎麼建議你開始？

如果你今天第一次做這條線，我會建議你這樣排：

1. 先把本機 Claude Code 用順
2. 先寫一份最基本的 CLAUDE.md
3. 先用 /install-github-app 裝起來
4. 先做 @claude review 或 issue comment，不要一開始就做最重的自動實作
5. 跑順後，再加排程 workflow 或更進階 prompt

不要一開始就設成「Claude 來幫我全自動接 issue、寫功能、合併 PR」。

這種通常不是做不到，而是你根本還沒有足夠的 repo 規則可以讓它穩定做。

Claude Code GitHub Actions 常見問題 FAQ

Claude Code GitHub Actions 要付費嗎？

會牽涉兩種成本：GitHub Actions runner 分鐘數和 Claude token 使用量。不是只有 API 成本。

Claude Code GitHub Actions 一定要自己寫 YAML 嗎？

不一定。官方推薦先用 Claude Code terminal 裡的 /install-github-app，它會引導你完成較快的安裝流程。

Claude Code GitHub Actions 可以只用在 review 嗎？

可以。這其實是很好的起點。你可以先把它當成第一層 reviewer，再慢慢擴到 issue 實作或排程型自動化。

Claude Code GitHub Actions 和本機 Claude Code 會互相取代嗎？

不會。比較好的分工是：本機 Claude Code 處理同步工作和深度理解，GitHub Actions 處理 issue、PR 和團隊協作入口。

Claude Code GitHub Actions 為什麼要寫 CLAUDE.md？

因為 Claude 不只看 prompt，也會看 repo root 的 CLAUDE.md。這個檔案可以讓它更懂你的規範、風格和專案慣例。

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

不是。GitHub app 是權限與 repo 整合層；GitHub Actions workflow 是執行層。你要讓 @claude 能真的動起來，通常 app、workflow、secret 三個都要到位。

結語：這條線的價值，不是自動化，是協作入口

很多人一看到 Claude Code GitHub Actions，第一反應是：

「太好了，終於可以把寫程式外包給 GitHub bot。」

但我覺得這樣理解太淺。

這條線真正有價值的地方，不是完全自動化，而是你終於把 Claude 帶進團隊最常碰到的入口：

• issue
• PR
• review
• workflow

也就是說，Claude 不再只是你自己電腦裡的一個助理，而是開始出現在團隊的協作介面裡。

這很值得做，但前提不是先追滿配，而是先把 repo 規則、權限和驗收習慣收好。你先把這三件事收穩，GitHub Actions 才會真的變成加速器，而不是噪音來源。

參考來源

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

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