Claude Code｜GitHub Actions 整合

GitHub Actions 可以在儲存庫事件或手動觸發時執行 Claude Code。本篇建立一個只讀的手動工作，讓它檢查 README 並把結果留在執行紀錄。完成後你會知道 workflow、GitHub App、認證秘密與模型任務各自負責什麼，也能停止後續執行。

請使用自己的測試儲存庫，具備管理 Actions、安裝 GitHub App 與設定 Secrets 的權限，並先理解非互動執行。本篇需要有效的 Claude API 認證並可能產生費用，不會因為 GitHub 工作顯示綠燈就代表模型用量免費。

先準備四個部分

閱讀完整文字說明

GitHub Actions 整合，以流程和文件圖形呈現教學重點。

Workflow 定義觸發與 runner，checkout 取得程式碼，Claude GitHub App 提供 GitHub 整合權限，Claude 認證則提供模型存取。GitHub token 與 Anthropic API key 是不同憑證，不可互換。

在測試儲存庫建立 README，寫下專案用途、npm start 與 npm test。這是本次只讀任務的輸入，應先提交到預定分支。不要使用真正的客戶資料、私人環境檔或正式部署設定作為第一個測試材料。

安裝與認證

依官方流程安裝 Claude GitHub App，只選擇需要的測試儲存庫。閱讀授予的權限，了解 App 安裝範圍與單一 workflow 的 permissions 是不同層次。組織可能要求管理者核准，沒有權限時先由管理者處理。

在儲存庫 Settings 的 Actions Secrets 建立 ANTHROPIC_API_KEY，值來自 Claude Console。秘密只填入 GitHub 的專用欄位，不寫入 YAML、README 或聊天。若採官方支援的訂閱長期權杖，應使用另一個對應 secret 與 claude_code_oauth_token 欄位，不能只換秘密值卻保留錯誤輸入名稱。

快速入口 /install-github-app 會協助安裝與準備 workflow 分支，但也可能推送分支與準備 PR。使用前要知道它包含哪些外部動作；本篇採手動建立最小檔案，讓你逐行看懂要執行的內容。

建立手動觸發的工作

新增 .github/workflows/claude-readme-check.yml，提交到測試儲存庫預設分支。workflow_dispatch 讓你從 Actions 頁手動執行，不會因每個一般留言自動啟動模型。以下版本名稱來自查證時官方文件，正式使用可依團隊規則鎖定審查過的提交版本。

name: Claude README check
on:
  workflow_dispatch:
jobs:
  readme:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          persist-credentials: false
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            只讀取 README.md，列出專案用途、啟動與測試命令。
            若有缺漏，列出缺少項目。
            不修改檔案、不提交、不發布留言或建立 PR。
            把結果留在本次執行輸出，沒有執行測試就明確註明。
          claude_args: '--tools "Read" --allowedTools "Read" --max-turns 4'

這個例子沒有 shell、寫檔或留言工具，目標只需讀取一份文件。id-token: write 是官方 GitHub App 認證流程需要的權限，不是授權模型寫入儲存庫內容。不要因為看到 write 字樣就把它與 contents: write 混為一談。

觸發一次並查看證據

到 Actions 選取 Claude README check，使用 Run workflow，確認選擇預定分支。打開這次 run，依序查看 checkout、Claude 認證與任務輸出。保存 run URL、提交 SHA 與結果摘要，方便之後重現。

成功時應列出 README 中真實存在的用途、啟動與測試命令。它沒有執行 npm test，因此不能宣稱測試通過。也要核對儲存庫沒有新提交、PR 或留言，符合本次只讀範圍。

若工作失敗，先判斷是 YAML、runner、App 認證、API 認證還是模型回合上限。不要一開始就把工具權限擴大為全部；讀取一份 README 不應需要部署權限或完整 shell。

延伸到議題與 PR 前的準備

@claude 不是安裝 App 後在任何地方都會自動生效，還需要支援事件的 workflow。若要採用官方留言範例，閱讀觸發條件、使用者權限檢查、工具授權與輸出位置，先在測試議題驗證一次。

公開儲存庫的 fork PR 通常無法取得一般秘密，這是重要的隔離邊界。不要為了讓 fork 工作跑起來，直接改成可以讀秘密又執行不受信任程式碼的流程。外部留言與 PR 內容都應被當成待處理資料，而不是自動擴權的指令。

如果加入寫入能力，提示應指定可改檔案、目標分支與是否可以留言。建立 PR、通過 CI、合併與部署是不同狀態，最後報告必須逐項核對，不用「已完成」涵蓋所有尚未發生的步驟。

停止與收尾

正在執行時可在 run 頁取消；停止未來觸發則停用或移除對應 workflow。刪除 GitHub Secret 不等於撤銷原 API key，需要到 Claude Console 另外取消。若不再使用 App，也從 GitHub 安裝設定移除其儲存庫存取。

小練習是完成一次正常 README 檢查，再移除文件中的測試說明，確認第二次能指出缺漏。完成判準是兩次 run 對應正確提交、結果可核對、沒有外部寫入，並已學會取消與停用。

回 Claude Code 教學總目錄

• AI 工具
• 教學
• Claude Code