Stage 01

怎麼寫出好維護的 workflow?

把重複的流程做成範本,輸入和 secrets 怎麼傳也一次弄清楚。

  1. 1. 統一新專案的 workflow 起點

    GitHub Actions 組織 Workflow Template:用 .github 統一新專案 CI 起點

    GitHub Actions 可用組織的 .github repository 提供 workflow template。本文示範 workflow-templates、properties.json、$default-branch 與 filePatterns,並說明何時改用 reusable workflow。

  2. 2. 確認共用 workflow 的 secrets

    GitHub Actions reusable workflow 的 secrets: inherit 怎麼用?

    GitHub Actions reusable workflow 不會自動收到 caller 的 secrets。本文比較明確傳遞與 secrets: inherit,整理直接呼叫、巢狀 workflow、environment secrets 與 Dependabot 的排錯邊界。

  3. 3. 正確判讀手動輸入的布林值

    GitHub Actions workflow_dispatch 的 boolean 為何要用 inputs context

    GitHub Actions 手動 workflow 的 boolean input 在 inputs 與 github.event.inputs 中型別不同。本文用部署範例說明條件式為何應優先讀取 inputs,避免字串造成誤判。

  4. 4. 在同一個 job 平行執行步驟

    GitHub Actions 步驟怎麼平行執行?用 background、wait 與 parallel

    GitHub Actions 現在可用 parallel、background、wait、wait-all 與 cancel 管理同一個 job 的並行工作。本文分開獨立建置、背景服務、失敗回報與清理流程,並說明何時改用 matrix 或不同 job。

Stage 02

workflow 沒跑或被中斷?

從必要檢查、部署排隊和核准狀態,找出它停在哪裡。

  1. 5. 找出 Pending 的必要檢查

    GitHub Actions workflow 被跳過後卡在 Pending?先處理 required check

    GitHub Actions 因 paths、branches 或 skip commit 被跳過時,required check 可能停在 Pending,讓 Pull Request 無法合併。本文整理原因、判斷方法與 workflow、job、merge queue 的修法。

  2. 6. 安排部署佇列與取消行為

    GitHub Actions concurrency 怎麼設:部署工作流避免互相取消的 queue 選擇

    GitHub Actions concurrency 怎麼設定才不會取消重要部署?本文說明 group、cancel-in-progress 與 queue 的差異,協助你依 preview 或 production 的發布需求管理同組 workflow。

  3. 7. 檢查等待核准的執行來源

    GitHub Actions workflow 被保留等待核准怎麼辦?先做來源與權限檢查

    GitHub Actions 會自動保留部分疑似惡意的 public repository workflow,等待有 write 權限的協作者核准。本文整理核准前的來源、diff、secrets 與替代處理流程。

Stage 03

Runner 和權限設對了嗎?

先確認 Runner 環境,再限制 PR 和快取能做的事,降低被濫用的風險。

  1. 8. 盤點自架 Runner 的版本

    GitHub Actions 自架 Runner 版本怎麼盤點?9/29 起進入強制期

    GitHub Enterprise Cloud 自架 Runner 最低版本強制自 2026 年 9 月 29 日起生效。本文說明 2.329.0 註冊門檻、執行版本差異,以及用 API 與 image 清單排查排程風險;GitHub Enterprise Server 不受影響。

  2. 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 更新、暫時回退與驗證步驟。

  3. 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 受影響前完成遷移,避免作業系統與工具版本改變後才發現失敗。

  4. 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 選擇。

  5. 12. 檢查 PR checkout 的權限

    GitHub Actions 的 pull_request_target 為何突然擋住 checkout?先分清楚安全邊界

    actions/checkout v7 會阻止 pull_request_target 直接取用 fork PR 程式碼。本文說明受影響流程、事件該怎麼選、正確改法與何時才能明確放行,避免高權限 workflow 執行不可信內容。

  6. 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。

  7. 14. 限制快取的讀寫權限

    GitHub Actions cache-mode 怎麼設才安全?restore-keys 仍不是可信來源

    GitHub Actions 新增 cache-mode,可用 read、write、write-only 或 none 限制快取操作。本文整理 workflow/job 覆寫、低信任事件、restore-only 與避免 cache poisoning 的設定邊界。

  8. 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 權限與除錯順序。

Stage 04

產出的檔案可信嗎?

檢查上傳了什麼、誰拿得到,以及怎麼證明檔案真的出自你的流程。

  1. 16. 確認隱藏檔案的上傳規則

    GitHub Actions artifact 少了 .env?upload-artifact 的隱藏檔案安全設定

    GitHub Actions 使用 upload-artifact 後找不到 .output 或 .config 等隱藏檔案時,先確認 action 版本與 include-hidden-files。本文示範安全的 allowlist、排除敏感檔案、失敗條件與 artifact 驗證流程。

  2. 17. 隔離 artifact 與 secrets

    GitHub Actions workflow_run 安全怎麼設?先隔離 artifact 與 secrets

    GitHub Actions 的 workflow_run 能在非特權 CI 完成後執行留言或部署,但後續流程會取得 secrets 與可寫入 token。本文用 artifact 只傳資料、$RUNNER_TEMP 驗證與最小 permissions,整理安全邊界。

  3. 18. 替 release artifact 記錄來源

    GitHub Actions artifact attestations 實作:替 release artifact 補 provenance

    GitHub Actions 的 artifact attestations 能把 release 檔案或容器映像與 workflow、repository、commit 綁在一起。本文用 actions/attest@v4 示範權限、產生與 gh verify 驗證流程。

  4. 19. 確認保留期限會清掉哪些紀錄

    GitHub Actions 保留期限將管 workflow runs:2026 年 10 月前要檢查什麼

    GitHub Actions 將從 2026 年 10 月 1 日起讓 checks、workflow runs 與 statuses 跟著 artifact 和 log retention 清理。本文整理影響範圍、設定位置、成本差異與歸檔做法,避免歷史 CI 證據突然消失。