GitHub Actions ubuntu-latest 要換 Ubuntu 26.04？遷移檢查清單

先看這次遷移會改變什麼#

Ubuntu 26.04 runner 已正式提供下列常用 label：

這些 label 只告訴你 runner image 的選擇，不保證所有預裝工具都與舊 image 相同。Ubuntu 26.04 的 image readme 會列出作業系統和工具清單，但你的 workflow 仍應該把真正需要的 Node.js、Python、Java、瀏覽器或 CLI 版本明確安裝，而不是依賴「剛好預裝」。

1. 先盤點 workflow 的 runner 與隱藏依賴#

在 repository 根目錄搜尋所有 runs-on，包含 reusable workflow 和 matrix：

1
rg -n --glob '.github/workflows/**' \
2
  'runs-on:|ubuntu-latest|ubuntu-[0-9]{2}\.[0-9]{2}|arm' .

接著把每條 job 的依賴記下來：

• 是否直接使用 ubuntu-latest，或由 ${{ matrix.os }} 間接指定。
• 是否安裝依賴於 Ubuntu image 的 system package、OpenSSL、Python、Java 或 Docker 行為。
• 是否使用只提供 x64 binary 的 action、CLI 或 native Node module。
• cache key、artifact 名稱或測試結果是否混用了不同 OS／架構。
• release、deploy、migration job 是否有 production 權限，不能直接拿來做第一次測試。

若 workflow 很多，可以先列出 label 而不改檔案：

1
rg -n --no-heading --glob '.github/workflows/**' 'runs-on:' .

這一步的價值是找出「表面上只有一個 latest，實際上被多個 release job 共用」的情況。先分辨測試、建置與部署責任，後面的釘選策略才不會把所有工作流程一起凍結。

2. 用非阻斷矩陣測試 Ubuntu 26.04#

先讓同一組測試同時跑舊版與新版，並把新版 job 設成不阻斷主流程。等結果穩定後，再移除 continue-on-error 或改變主要 label：

1
jobs:
2
  test:
3
    strategy:
4
      fail-fast: false
5
      matrix:
6
        os: [ubuntu-24.04, ubuntu-26.04]
7
    runs-on: ${{ matrix.os }}
8
    continue-on-error: ${{ matrix.os == 'ubuntu-26.04' }}
9
    steps:
10
      - uses: actions/checkout@v5
11
      - uses: actions/setup-node@v6
12
        with:
13
          node-version-file: .nvmrc
14
          cache: npm
15
      - run: npm ci
16
      - run: npm test

這個範例只示範遷移矩陣；actions/checkout、actions/setup-node 的版本和 cache 設定仍要依你的 repository policy 管理。若沒有 .nvmrc，請改成明確的 runtime 版本，避免 OS 遷移與 Node 升級同時發生而難以定位。

比較結果時，不要只看 job 綠不綠。至少保留兩邊的：

1. 安裝與 lockfile 錯誤。
2. native module 編譯輸出。
3. lint、型別檢查和測試失敗的第一個堆疊。
4. artifact、cache hit rate 和產出檔案的差異。
5. deploy 前的 dry run 或設定檔驗證結果。

3. 在 job 內記錄實際的版本#

同一個 major 版本也可能因 image 更新而有不同 patch 版本。針對會影響產出的工具，在測試階段先輸出版本，讓失敗可以和 image 變更對照：

1
- name: Record runner environment
2
  run: |
3
    cat /etc/os-release
4
    uname -a
5
    node --version || true
6
    npm --version || true
7
    python3 --version || true
8
    java -version || true
9
    docker --version || true

正式 job 不需要無條件安裝所有語言；原則是「凡是會改變編譯或測試結果的工具，都應該由 workflow 明確指定版本」。GitHub runner image 只應提供底層環境，不能當成 lockfile。

如果你依賴 image 預裝的 CLI，至少把 image readme 的查核日期和 CLI 版本納入 migration note。更穩定的方式是使用官方 setup action、容器或專案自己的 toolchain，並在 cache key 中納入 OS 與架構：

1
- uses: actions/cache@v4
2
  with:
3
    path: ~/.cache/my-tool
4
    key: ${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/lockfile') }}

這個 cache key 只是示意；實際 cache 路徑、action 版本和 lockfile 名稱要依專案調整。重點是不要讓 Ubuntu 24.04 與 26.04、x64 與 Arm 共用一份不相容的 native cache。

4. 需要時暫時釘選 ubuntu-24.04#

如果新版測試還有阻斷問題，可以把 production job 從 ubuntu-latest 改為 ubuntu-24.04，並建立明確的再評估日期：

1
jobs:
2
  release:
3
    runs-on: ubuntu-24.04

釘選不是永久解法。你仍要：

• 在 issue 或 migration checklist 記錄阻斷原因、負責人和回測條件。
• 確認第三方 action、native dependency 和 Docker base image 的支援範圍。
• 把 ubuntu-26.04 測試保留在 pull request 或 nightly workflow。
• 在下一個 image／runtime 版本更新前重新檢查，而不是無限延後。

不要把 ubuntu-24.04 當成「完全不會變」的承諾；它只是目前可用的明確版本 label。未來若要移到其他 image，仍應重跑同一套盤點與矩陣驗證。

5. 另外驗證 Arm runner#

ubuntu-26.04-arm 不是把 x64 job 的 label 貼上去就完成。Arm 測試至少要確認：

• 使用的 Docker image 是否有 multi-architecture manifest。
• npm、Python 或其他依賴中的 native module 是否有 Arm wheel／binary，或能在 runner 上編譯。
• 第三方 action 是否支援目前架構，尤其是包裝 CLI 的 action。
• cache 與 artifact 是否把 runner.arch 納入識別。
• 測試資料、timeout 與 parallelism 是否因硬體差異需要調整。

如果 production 仍是 x64，不必為了追求 label 對稱而把所有 deploy job 改成 Arm；先把 Arm 當成明確的相容性測試目標。

遷移完成前的檢查清單#

可以在 pull request 描述中逐項勾選：

• 所有 runs-on 來源都已找到，包含 reusable workflow 和 matrix。
• 以 ubuntu-26.04 跑過測試，並保存失敗輸出與工具版本。
• ubuntu-latest 與 ubuntu-24.04 的差異已被分類，不把偶發失敗直接歸因於 OS。
• 重要 runtime、CLI、瀏覽器與 native dependency 已明確指定。
• cache、artifact 和測試結果不會跨 OS／架構誤用。
• release／deploy job 有單獨的核准與回復策略。
• 若暫時釘選 ubuntu-24.04，已留下再評估日期和負責人。
• 若使用 Arm，已確認 image、action 和 native dependency 的架構支援。

常見問題#