GitHub Actions runner 镜像更新前如何验证项目依赖

GitHub Actions runner 镜像更新前，最稳妥的验证方式不是把 ubuntu-latest 再跑一遍，而是把 workflow 的真实依赖拆成“项目锁定的版本、由 runner 提供的工具、由系统仓库提供的组件”三层，再用旧标签和候选标签做一次可比较的回归。这样即使构建失败，也能知道是镜像变化、项目配置还是外部服务造成的。

官方地址：https://github.com/actions/runner-images

镜像更新带来的风险不止是系统标签变化

GitHub 官方维护的 runner-images 仓库会公布镜像版本和软件变更。当前 release 页面能看到 Ubuntu 24.04 的镜像版本、操作系统补丁，以及 Kotlin、Docker Buildx、Minikube、云 CLI、Rust 等工具的前后版本。也就是说，workflow 里即使没有改一行 YAML，预装命令的行为也可能发生变化。

另一个容易漏掉的信号是弃用。官方公告显示，ubuntu-22.04 将从 2026 年 9 月 17 日开始进入弃用阶段，并计划在 2027 年 4 月 17 日完全停止支持。日期会随官方计划调整，但排查思路不变：看到弃用公告，就要把标签迁移和依赖回归放进同一个变更单，而不是等构建突然排队失败。

先建立三列清单：

先把依赖清单从工作流里捞出来

不要只看 runs-on。沿着 workflow 的每个 job 读取 setup action、缓存键、脚本和容器配置，找出那些“没有写版本但实际会被使用”的命令。下面是一个缩小后的写法，重点是让运行时版本来自项目配置，而不是 runner 恰好预装的版本：

jobs:
  test:
    runs-on: ubuntu-24.04 # 中文注释：迁移验证阶段先使用明确标签
    steps:
      - uses: actions/checkout@v4 # 中文注释：拉取包含 lockfile 的项目
      - uses: actions/setup-node@v4
        with:
          node-version-file: .nvmrc # 中文注释：版本由仓库文件统一管理
          cache: npm # 中文注释：缓存键跟随 package-lock.json
      - run: npm ci # 中文注释：严格按锁定文件安装，失败时立即暴露漂移
      - run: npm test -- --runInBand # 中文注释：先完成确定性的最小回归

如果项目用 Java、Go 或 Python，原则相同：把版本写进 setup action、工具链文件或容器定义，把依赖写进对应 lockfile。对于确实依赖系统包的步骤，额外记录包名、用途和最低版本；不要把一次运行时打印出来的完整环境误当成项目契约。

用双环境矩阵验证，而不是只看能否启动

验证重点应当是“旧环境和候选环境是否产生相同的项目结果”。可以在迁移分支临时加入矩阵，把安装、编译、测试、制品生成放入同一个 job：

strategy:
  fail-fast: false # 中文注释：保留两套环境的完整结果，便于定位差异
  matrix:
    runner: [ubuntu-22.04, ubuntu-24.04] # 中文注释：旧标签与候选标签并排回归

steps:
  - uses: actions/checkout@v4 # 中文注释：两套环境使用同一份提交
  - uses: actions/setup-python@v5
    with:
      python-version-file: .python-version # 中文注释：不依赖镜像默认 Python
  - run: python -m pip install --require-hashes -r requirements.txt # 中文注释：校验依赖哈希，避免静默漂移
  - run: python -m pytest -q # 中文注释：测试失败时保留 runner 和 Python 版本信息
  - run: ./ci/package.sh # 中文注释：比较最终制品，而不只比较测试退出码

回归结果至少分成三类。第一类是工具缺失或版本差异，例如脚本依赖某个 CLI 的旧参数；第二类是系统差异，例如 OpenSSL、证书、Shell 或文件权限变化；第三类是网络和外部服务波动。只有前两类适合直接归因于镜像，第三类要用重试、服务 mock 或独立探针排除噪声。

把失败分类后再决定切换还是回滚

不要因为新标签能完成单元测试就直接切生产。先看关键制品是否一致、部署脚本是否通过、缓存是否可复用，以及失败是否集中在某一个预装工具。GitHub 文档建议用 action 与版本选择来交互软件，这正是降低镜像漂移影响的办法。

• 可控差异：补上 setup action、lockfile 或容器版本，再重跑矩阵。
• 真实不兼容：暂时固定旧标签，记录受影响命令和替代方案，并设置迁移截止日期。
• 镜像弃用：优先迁移到明确的新标签，不要继续依赖 latest 争取“自动适配”。
• 外部波动：单独复跑或替换探针，避免把网络偶发失败写进镜像结论。

最终的检查单可以只有五项：runner label 是否明确、setup action 是否固定关键工具、lockfile 是否参与安装、两套环境的制品是否可比、失败后是否能一键回到旧标签。五项都能回答，镜像更新才算完成验证。

常见问题

为什么 workflow 没改也可能突然失败？

因为浮动标签或预装工具会随镜像发布变化。先对照 release 的变更表，再检查脚本是否依赖未固定的 CLI 或系统包。

把 runner 标签固定后就完全稳定了吗？

不能。固定标签能减少操作系统大版本漂移，但镜像仍可能收到补丁和工具更新；关键运行时和项目依赖仍应由 setup action、lockfile 或容器管理。

什么时候应该使用自有镜像？

当项目依赖的系统包、证书、编译器或合规基线需要长期一致，且每次在 runner 上安装成本很高时，可以评估自有镜像；否则先用明确标签和可重复安装降低维护成本。

runner 镜像更新不是一次“换系统”的动作，而是一次依赖契约复查。把官方变更记录、项目锁定文件和双环境结果放在同一条证据链里，团队就能把不可预期的 CI 波动，变成可回归、可灰度、可回滚的工程决策。