適合:維護 GitHub Actions 的開發者、使用自架 Runner 的團隊
GitHub Actions 排錯
workflow 沒跑、跑到一半被取消,或權限設定讓人提心吊膽?這個專題從寫出好維護的 workflow 開始,整理流程卡住時怎麼查、Runner 和權限怎麼設,以及怎麼確認產出的檔案可信。
怎麼寫出好維護的 workflow?
把重複的流程做成範本,輸入和 secrets 怎麼傳也一次弄清楚。
- 1. 統一新專案的 workflow 起點
GitHub Actions 組織 Workflow Template:用 .github 統一新專案 CI 起點
GitHub Actions 可用組織的 .github repository 提供 workflow template。本文示範 workflow-templates、properties.json、$default-branch 與 filePatterns,並說明何時改用 reusable workflow。
- 2. 確認共用 workflow 的 secrets
GitHub Actions reusable workflow 的 secrets: inherit 怎麼用?
GitHub Actions reusable workflow 不會自動收到 caller 的 secrets。本文比較明確傳遞與 secrets: inherit,整理直接呼叫、巢狀 workflow、environment secrets 與 Dependabot 的排錯邊界。
- 3. 正確判讀手動輸入的布林值
GitHub Actions workflow_dispatch 的 boolean 為何要用 inputs context
GitHub Actions 手動 workflow 的 boolean input 在 inputs 與 github.event.inputs 中型別不同。本文用部署範例說明條件式為何應優先讀取 inputs,避免字串造成誤判。
- 4. 在同一個 job 平行執行步驟
GitHub Actions 步驟怎麼平行執行?用 background、wait 與 parallel
GitHub Actions 現在可用 parallel、background、wait、wait-all 與 cancel 管理同一個 job 的並行工作。本文分開獨立建置、背景服務、失敗回報與清理流程,並說明何時改用 matrix 或不同 job。
workflow 沒跑或被中斷?
從必要檢查、部署排隊和核准狀態,找出它停在哪裡。
- 5. 找出 Pending 的必要檢查
GitHub Actions workflow 被跳過後卡在 Pending?先處理 required check
GitHub Actions 因 paths、branches 或 skip commit 被跳過時,required check 可能停在 Pending,讓 Pull Request 無法合併。本文整理原因、判斷方法與 workflow、job、merge queue 的修法。
- 6. 安排部署佇列與取消行為
GitHub Actions concurrency 怎麼設:部署工作流避免互相取消的 queue 選擇
GitHub Actions concurrency 怎麼設定才不會取消重要部署?本文說明 group、cancel-in-progress 與 queue 的差異,協助你依 preview 或 production 的發布需求管理同組 workflow。
- 7. 檢查等待核准的執行來源
GitHub Actions workflow 被保留等待核准怎麼辦?先做來源與權限檢查
GitHub Actions 會自動保留部分疑似惡意的 public repository workflow,等待有 write 權限的協作者核准。本文整理核准前的來源、diff、secrets 與替代處理流程。
Runner 和權限設對了嗎?
先確認 Runner 環境,再限制 PR 和快取能做的事,降低被濫用的風險。
- 8. 盤點自架 Runner 的版本
GitHub Actions 自架 Runner 版本怎麼盤點?9/29 起進入強制期
GitHub Enterprise Cloud 自架 Runner 最低版本強制自 2026 年 9 月 29 日起生效。本文說明 2.329.0 註冊門檻、執行版本差異,以及用 API 與 image 清單排查排程風險;GitHub Enterprise Server 不受影響。
- 9. 排查 checkout v5 的 Node 24 錯誤
actions/checkout@v5 出現 Node 24 錯誤怎麼辦?先更新 GitHub Actions runner
GitHub Actions 使用 actions/checkout@v5 後若出現 Node 24 或 runner 版本錯誤,問題通常在 Actions runner,不是 setup-node。本文整理 hosted、self-hosted 與 act 的分流,並提供 runner 更新、暫時回退與驗證步驟。
- 10. 驗證 Ubuntu Runner 環境遷移
GitHub Actions ubuntu-latest 要換 Ubuntu 26.04?遷移檢查清單
GitHub Actions 的 ubuntu-latest 將在 2026 年 10 月 19 日至 11 月 19 日逐步移到 Ubuntu 26.04。本文整理 label 測試、預裝工具盤點、版本釘選、Arm runner 與回復流程,協助你在 CI 受影響前完成遷移,避免作業系統與工具版本改變後才發現失敗。
- 11. 驗證 Windows ARM 的 VS2026 映像
GitHub Actions windows-11-arm 要換 VS2026?先用新 Runner label 驗證
GitHub Actions 的 windows-11-arm 將在 2026 年 9 月 21–30 日逐步改用 Visual Studio 2026。本文整理 windows-11-vs2026-arm 的測試方式、VS2022 相容性檢查與不想跟著遷移時的 runner 選擇。
- 12. 檢查 PR checkout 的權限
GitHub Actions 的 pull_request_target 為何突然擋住 checkout?先分清楚安全邊界
actions/checkout v7 會阻止 pull_request_target 直接取用 fork PR 程式碼。本文說明受影響流程、事件該怎麼選、正確改法與何時才能明確放行,避免高權限 workflow 執行不可信內容。
- 13. 設定 workflow 的觸發保護
GitHub Actions workflow execution protections GA 怎麼設?用 ruleset 限制誰能觸發 CI
GitHub Actions workflow execution protections 已正式 GA,可用 ruleset 限制 workflow、actor 與 event。本文更新 evaluate mode、REST API、pull_request_target 預設防護與 2026 rollout。
- 14. 限制快取的讀寫權限
GitHub Actions cache-mode 怎麼設才安全?restore-keys 仍不是可信來源
GitHub Actions 新增 cache-mode,可用 read、write、write-only 或 none 限制快取操作。本文整理 workflow/job 覆寫、低信任事件、restore-only 與避免 cache poisoning 的設定邊界。
- 15. 遷移 OIDC 信任政策
GitHub Actions OIDC immutable subject claims:IAM 信任政策怎麼遷移?
GitHub Actions OIDC 的新 repository 可能使用含 owner ID 與 repository ID 的 immutable subject claim。本文拆解 sub 格式、舊 repo opt-in、cloud trust policy、id-token 權限與除錯順序。
產出的檔案可信嗎?
檢查上傳了什麼、誰拿得到,以及怎麼證明檔案真的出自你的流程。
- 16. 確認隱藏檔案的上傳規則
GitHub Actions artifact 少了 .env?upload-artifact 的隱藏檔案安全設定
GitHub Actions 使用 upload-artifact 後找不到 .output 或 .config 等隱藏檔案時,先確認 action 版本與 include-hidden-files。本文示範安全的 allowlist、排除敏感檔案、失敗條件與 artifact 驗證流程。
- 17. 隔離 artifact 與 secrets
GitHub Actions workflow_run 安全怎麼設?先隔離 artifact 與 secrets
GitHub Actions 的 workflow_run 能在非特權 CI 完成後執行留言或部署,但後續流程會取得 secrets 與可寫入 token。本文用 artifact 只傳資料、$RUNNER_TEMP 驗證與最小 permissions,整理安全邊界。
- 18. 替 release artifact 記錄來源
GitHub Actions artifact attestations 實作:替 release artifact 補 provenance
GitHub Actions 的 artifact attestations 能把 release 檔案或容器映像與 workflow、repository、commit 綁在一起。本文用 actions/attest@v4 示範權限、產生與 gh verify 驗證流程。
- 19. 確認保留期限會清掉哪些紀錄
GitHub Actions 保留期限將管 workflow runs:2026 年 10 月前要檢查什麼
GitHub Actions 將從 2026 年 10 月 1 日起讓 checks、workflow runs 與 statuses 跟著 artifact 和 log retention 清理。本文整理影響範圍、設定位置、成本差異與歸檔做法,避免歷史 CI 證據突然消失。