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

先分辨是「沒有 runner」還是「runner 太舊」#

在 repository 的 Actions 頁面打開卡住的 job，先看它要求的 labels；再到 organization 或 repository 的 Settings → Actions → Runners 確認對應 runner 是否 online、idle，以及最後活動時間。若是 autoscaling 或 ephemeral runner，也要檢查 controller 是否確實建立新 pod／VM。

常見現象不只一種：

不要只靠自動更新#

一般 self-hosted runner 預設會在有新版本時更新。但 Docker、Kubernetes 與 ephemeral runner 常刻意使用 --disableupdate，避免每次新容器都下載更新；這是合理的部署設計，但更新責任就移到 image 的維護流程。

GitHub 文件指出，停用自動更新後仍必須定期更新；新版本發布後超過 30 天，服務可能不再把 job 排給該 runner。遇到 critical security update 時，更新前也可能停止排程。因此「image 可以穩定重建」不等於「版本可以一直固定」。

可回復的更新流程#

1. 記錄現況：保留目前 runner image tag、runner group、labels 與最近成功 job。
2. 更新測試 runner：先替非正式 repository 或獨立 runner group 更新 runner binary／image。
3. 跑代表性 workflow：至少包含 checkout、cache、需要的 container 或部署權限。
4. 逐批替換：讓舊 runner drain，不接新 job 後再替換；不要在一個唯一 runner group 上直接全數停機。
5. 確認 GitHub UI：確認新 runner 成為 online，並實際完成一個 job，不只看主機上的 process 存活。

如果使用 Actions Runner Controller（ARC），更新通常應透過 controller 與 runner image 的既定發版方式完成，而不是進入單一 pod 手動改 binary。這樣下次 autoscaling 才不會又生出舊版 runner。

把版本檢查放進日常維運#

最小化做法是訂閱 actions/runner releases，並把 runner image tag 或版本列入每月維護項目。對 --disableupdate 的 runner，可在 CI 或監控中記錄目前版本，讓「job 排不動」不會成為第一次知道版本落後的時機。

本文查核日為 2026-09-29。強制日與各版本 runtime 期限可能改動；不要把單一日期或最低註冊版本複製進 runbook 後就忘記回看公告和 API。

版本強制期間，用 API 做一次版本盤點#

GitHub 的 self-hosted runner REST API 回傳每台 runner 的 version、status、busy、ephemeral 與 labels。這比從個別 VM 登入檢查更適合先找出整批舊 image；呼叫 organization endpoint 需要有讀取 self-hosted runners 的適當權限。

1
gh api --paginate '/orgs/ORG/actions/runners?per_page=100' \
2
  --jq '.runners[] | [.name, .version, .status, .ephemeral, ([.labels[].name] | join(","))] | @tsv'

輸出後至少分成三群：可自動更新的常駐 runner、由 image 建立的 ephemeral runner，以及 offline 或不再使用但仍註冊的 runner。2.329.0 是重新註冊的最低門檻，不是可以永久停留的執行版本；即使剛好高於它，仍要在新 release 後 30 天內更新。

1
gh api '/orgs/ORG/actions/runners/deprecations/2.329.0' \
2
  --jq '[.runner_version, .runtime_deprecates_at] | @tsv'

常見問題#