GitHub Actions 新变化怎样检查工作流兼容性

GitHub Actions 这轮变化，真正容易让旧工作流失效的地方不在 YAML 是否还能解析，而在依赖引用、运行环境、历史记录和触发策略一起改变。兼容性检查建议按“依赖是否锁定、runner 是否还存在、记录是否保得住、触发是否会被策略拦截”四条线展开。

先盘点再启用策略：把每个 workflow 的 uses、runs-on、保留期需求和触发事件列成表，再分批迁移，最容易避免 CI 在同一天出现多种原因的失败。

官方地址：https://github.blog/changelog/

先看这四项变化会碰到哪里

这四项并不是同一种升级：锁文件和执行保护属于策略边界，runner 是环境替换，retention 是数据生命周期。迁移单里要分开记录负责人和回滚条件。

第一步：把 action 依赖锁住，再检查差异

官方的 workflow dependency lockfile 由 GitHub CLI 扩展生成，文件通常是 .github/workflows/actions.lock。它会记录 action 及其传递依赖对应的 commit；可复用工作流仍由定义它的仓库负责锁定。先在分支上生成，再把 workflow 和 lockfile 的完整差异一起审查。

# 安装官方 GitHub CLI 扩展；首次接入前先确认 uses 引用指向期望版本
gh extension install github/gh-actions-lock

# 扫描 .github/workflows 并生成或更新锁文件
gh actions-lock

# 只检查本地是否存在覆盖所有依赖的锁项，不修改文件
gh actions-lock --verify-local --no-fix

# 在拉取请求中检查锁文件是否过期
gh actions-lock --verify

不要直接手改 lockfile。重点看两类 diff：workflow 的 uses 是否从可变 tag 变成了明确版本，以及 lockfile 中的 commit、仓库身份是否出现意外变化。只有确认这些变更符合预期后，才在小范围打开 Require lockfile；企业版可先使用 Evaluate 模式观察会被阻断的运行。

第二步：扫描 runner 标签和工具链假设

如果工作流里还写着 macos-14、macos-14-large 或 macos-14-xlarge，要在 2026-11-02 前迁移。官方给出的替代方向包括 macos-15、macos-latest（当前指向 macOS 26）及相应的大规格标签。

# 找出固定的 macOS 14 runner；命令只读文本，不改变工作流
rg -n "macos-14|macos-latest|runs-on:" .github/workflows

# 检查 workflow 是否把 Xcode、架构或系统路径写死
rg -n "xcode-select|DEVELOPER_DIR|/Applications|arm64|x86_64" .github/workflows

替换标签不等于兼容性完成。macOS 15、macOS 26 和 Apple Silicon 可能带来 Xcode、系统 SDK、Homebrew 架构或缓存键变化。先复制一个 workflow 做回归，至少覆盖编译、测试、缓存恢复和产物上传；确定工具链后再合并主分支。对 macos-latest 则要接受它会随 GitHub 的迁移策略变化，关键发布链路更适合显式固定版本并定期升级。

第三步：把保留期和触发策略当成兼容性的一部分

从 2026-10-01 起，checks、workflow runs 和 statuses 也跟随 Actions retention 设置清理。若团队需要超过默认窗口的审计材料，不要等记录消失后再找；应提前提高允许范围内的保留期，或把必要日志、报告和元数据导出到自己的归档系统。

另一个高风险点是 pull_request_target。公共仓库的默认保护规则会在 2026-12-02 自动强制执行，依赖该事件读取 Secrets 或执行受信任代码的 workflow 要先用 Policy insights 找出受影响运行，再决定是改为更安全的事件、拆分受信任任务，还是为确有必要的 workflow 做明确 allowlist。不要为了“先跑起来”把来自 fork 的不可信代码直接放进带 Secrets 的任务。

on:
  pull_request:
    # 普通验证尽量使用 fork 隔离的事件，不把 Secrets 暴露给外部代码
    branches: [main]

permissions:
  # 默认最小权限，具体任务再在 job 级别增加
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: 运行测试
        run: go test ./...

这段示例只是兼容性审查的起点，不代表所有项目都能直接替换事件。若确实需要 pull_request_target，应把它与不可信代码检出、脚本执行和 Secrets 使用逐项拆开评估。

最后用一张迁移单收口

1. 列出每个 workflow 的 uses、runs-on、触发事件和是否依赖 Secrets。
2. 先生成 actions.lock，审查 commit 与仓库身份，再在一个仓库或一组 workflow 上试用策略。
3. 把 macOS 14 替换为明确的新标签，验证 Xcode、架构、缓存和产物，不只改一行 YAML。
4. 确认 retention 能覆盖审计周期；必须长期保存的结果在清理前导出。
5. 对 pull_request_target 使用 Policy insights 做预演，记录会被阻断的运行，最后才启用强制策略。

判断是否兼容的标准不是“今天能不能点绿色”，而是依赖版本、执行环境、可追溯记录和触发权限都能被团队解释。把这四类变化拆开推进，升级就能从一次大爆炸变成几次可回滚的小变更。

常见问题

actions.lock 能替代把 uses 固定到完整 SHA 吗？

不能简单画等号。锁文件提供另一层可审查的依赖记录，是否启用 Require lockfile 仍取决于仓库策略；已有 SHA pinning 也可以在分阶段迁移中继续保留。

使用 macos-latest 就不用做回归了吗？

不是。latest 方便跟随平台迁移，但系统、Xcode 和架构仍可能变化。发布链路应定期验证，或在需要稳定性的阶段使用显式 runner 标签。