GitHub Actions Runner Images 更新时如何验证构建矩阵

Runner Images 更新后，最容易误判的不是“某个 job 变红”，而是矩阵里不同标签实际落到什么环境。我的做法是先把固定标签和 -latest 并列跑一轮，在每个 job 开头记录 matrix.os、runner.os、runner.arch 和工具版本，再执行与正式流水线相同的构建命令。这样能看出是镜像迁移、预装工具变化，还是项目代码本身的问题。

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

先把要验证的 runner 组合写进矩阵

Runner Images 的 -latest 是会随新 GA 操作系统迁移的移动标签；固定标签则更适合作为发布基线。官方仓库说明迁移通常会提前公告并渐进进行。当前 Ubuntu 22 镜像已经公告将于 2026 年 9 月 17 日开始弃用，计划在 2027 年 4 月 17 日完全不再支持，仍使用它的项目应把这次矩阵验证当成迁移前检查。

先把矩阵做成“旧基线、目标环境、移动标签”三组。fail-fast: false 很重要：一个组合失败时，其余组合仍会运行并留下对比证据。

name: runner-image-matrix

on:
  workflow_dispatch:

jobs:
  verify:
    strategy:
      # 让每个 OS 组合都留下结果，避免首个失败掩盖后续环境
      fail-fast: false
      max-parallel: 3
      matrix:
        os: [ubuntu-22.04, ubuntu-24.04, ubuntu-latest]
        go: ['1.25.x']
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          # 语言版本固定，减少把镜像变化误当成 Go 版本变化
          go-version: ${{ matrix.go }}
      - name: Record runner identity
        shell: bash
        run: |
          # 只记录公开环境信息，不输出 secrets 或完整环境变量
          printf 'matrix.os=%s\n' '${{ matrix.os }}'
          printf 'runner.os=%s\n' '${{ runner.os }}'
          printf 'runner.arch=%s\n' '${{ runner.arch }}'
          printf 'matrix.go=%s\n' '${{ matrix.go }}'
          printf 'strategy=%s/%s\n' '${{ strategy.job-index }}' '${{ strategy.job-total }}'
          go version
      - name: Build and test
        run: |
          # 使用和正式流水线相同的构建与测试入口
          go test ./...
          go build ./...

这里的 matrix.os 是工作流声明值，runner.os 和 runner.arch 是当前 job 可读取的 runner 上下文。两者一起记录，才能发现标签拼写正确但架构不符合预期的情况。矩阵组合还会受维度数量影响，GitHub 文档给出的单次 workflow 上限是 256 个 job，因此不要为了“全覆盖”无限增加轴。

用日志证明每个组合跑在什么环境

验证步骤不应只执行一次“能不能编译”。我会把依赖安装、生成代码、构建和最小测试都保留，并为每个组合保存同样格式的开头日志。至少核对四列：声明的标签、实际系统与架构、工具版本、最终状态。

我更愿意把结果按组合保存，而不是只截图一个绿色总览：例如 ubuntu-24.04 + 1.25.x 成功，不能推出 ubuntu-latest + 1.25.x 也已经验证。若失败集中在移动标签，而固定标签成功，优先检查 Runner Images 的公告和预装软件清单；若所有标签都失败，先回到代码、依赖或凭据问题。

验证通过后怎样安排固定标签与 latest

发布链路需要可回退，所以我通常把生产 job 固定到已经通过构建和测试的 OS 标签；另建一个定时或手动 workflow 使用 -latest 做预检。这样移动标签发生迁移时，预检先暴露差异，正式发布仍有稳定基线。等目标固定标签在完整矩阵中通过，再单独提交一次修改发布标签的变更。

镜像更新还可能影响预装工具默认版本。Runner Images 仓库说明，默认版本更新一般会提前公告；因此排查时把“镜像标签变化”和“工具版本变化”分开记录，必要工具用 setup action 显式指定版本，不把预装版本当成长期契约。

相关问题

为什么两个 job 都显示 Linux，结果却不同？

runner.os 只有 Linux、Windows 或 macOS 这类系统级信息；镜像标签、架构、预装工具和系统库仍可能不同。应结合 matrix.os、runner.arch 和工具版本比较。

要不要直接把所有工作流改成 latest？

不建议一次性替换。先用矩阵验证目标环境，再让发布链路固定到通过的标签，把 latest 作为兼容性探测组；确认差异可接受后再迁移。

fail-fast=false 会让失败 job 自动重试吗？

不会。它只控制矩阵中其他 job 是否继续排队运行；重试、失败 job 重跑和代码修复仍需单独处理。