actions/checkout@v5 出現 Node 24 錯誤怎麼辦？先更新 GitHub Actions runner

先從錯誤訊息分流#

先在 workflow 與 job 記錄中確認三件事：

1
jobs:
2
  build:
3
    runs-on: ubuntu-latest
4
    steps:
5
      - uses: actions/checkout@v5

1
rg -n 'runs-on:|actions/checkout@|setup-node|container:|act' \
2
  .github/workflows .actrc Makefile package.json

接著依 runs-on 分流：

不要把 runs-on: self-hosted、label、container 與 workflow trigger 混在一起看。很多「我明明使用 ubuntu-latest」的案例，實際上是另一個 job、reusable workflow 或 matrix 分支用了舊的 self-hosted label。

hosted runner 和 self-hosted runner 要分開看#

GitHub-hosted runner 由 GitHub 管理 image 與 runner application；你能做的是確認 job log、image label 與官方服務狀態，並在短暫異常時重試或改用已支援的 label。不要在 workflow 中用 npm install 期待修改託管 runner 的核心版本。

self-hosted runner 則是團隊自己管理。官方文件說明，runner 預設會自動更新；若啟用了 --disableupdate，就必須由管理者手動更新。新的 Actions 功能可能要求較新的 runner，版本過舊時 job 可能排隊或在 action 啟動前失敗。

先在 GitHub repository 或 organization 的 Runners 頁面確認：

• 失敗 job 使用的 runner 名稱與 labels。
• log 顯示的 runner application 版本是否低於 v2.327.1。
• runner 是否被設成 --disableupdate，或服務帳號無法寫入更新目錄。
• 更新後 runner 是否真的離線、重新啟動，再以新版本上線。

如果需要逐台處理，可參考 self-hosted runner 更新清單；不要只在 workflow 中增加一個 Node 安裝 step，然後把相同的舊 runner label 留給所有 job。

更新 self-hosted runner 的正確範圍#

更新的目標是 runner application 與它的服務生命週期，不是專案依賴。建議順序是：

1. 保存失敗 job URL、runner name、runner version、OS／架構與 workflow commit。
2. 從 GitHub Runners 設定或官方 runner release 取得符合平台的版本，依團隊維運流程替換 runner。
3. 重新啟動 runner service，確認它重新註冊且 log 顯示新版本。
4. 用一個只包含 checkout 的最小 job 測試，再重跑完整 matrix。
5. 檢查其他 uses: action 是否也有新的最低 runner 要求。

更新自託管 runner 後，還要確認它能存取 action download、GitHub API、checkout 需要的 repository 與 credential。若 checkout 通過但後續 package install 失敗，那是另一個網路、權限或 Node runtime 問題，不要把所有錯誤都歸在 runner 版本。

為什麼 setup-node 不能修好 runner 錯誤#

actions/setup-node 是 workflow 中的一個 action step；它會在 runner application 已經啟動、並且能夠執行 action 之後，替後續腳本準備 Node.js。actions/checkout@v5 的 Node 24 runtime 則由 Actions runner 負責載入，發生錯誤的時間點可能早於 setup-node。

因此以下順序不能解決 runner 太舊：

1
steps:
2
  - uses: actions/setup-node@v4
3
    with:
4
      node-version: 22
5
  - uses: actions/checkout@v5

這段設定可以選擇專案腳本使用的 Node 版本，但不能把 runner application 升級，也不能讓舊 runner 執行它不支援的 action runtime。應先修 runner，再依專案需求設定 setup-node。

暫時回退時要保留什麼證據#

如果 self-hosted runner 由外部團隊管理、更新有變更窗口，可以把 checkout 暫時固定到仍可用的 v4，讓 CI 恢復，但要同時留下：

• 原始 Node 24／runner 版本錯誤與完整 job URL。
• 受影響的 runner labels、管理者與預計更新時間。
• 回退的 workflow commit，最好依團隊政策使用 tag 或 commit SHA pinning。
• 回退期間是否有安全掃描、權限或其他 action runtime 差異。

回退只處理事故期間的可用性，不代表 v5 需求消失。runner 更新後要再切回 v5，並刪除臨時 workaround；若團隊的安全政策不允許浮動 tag，回退與升級都應使用已審查的 SHA，而不是在失敗時任意改成另一個版本。

另外，actions/checkout 的 Node 24 runtime 與既有的 pull_request_target 權限風險是不同問題。若 workflow 同時使用該 trigger，仍要依 pull_request_target 的權限與 checkout 安全檢查 另外審查，不要把 runner 更新當成權限修正。

完成條件：action、runner 與 job 都通過#

修復完成後，至少確認：

1. 失敗 job 實際使用的 runner application 已達 v2.327.1 或更新版本。
2. actions/checkout@v5 在受影響的 runner、OS 與 container 組合中可以啟動。
3. setup-node 只負責專案需要的 Node 版本，沒有被當成 runner 更新手段。
4. self-hosted runner 的服務在重啟、斷線與自動更新後仍會重新註冊。
5. 完整 workflow 的 cache、submodule、LFS、private repository 與後續 build 都通過。

最後保留一份 runner version 與 workflow commit 的對照，下一次 action major 升級時就能先在 canary runner 驗證，不必等 production job 先失敗才知道 runtime 有最低版本門檻。

常見問題#