GitHub Actions 自托管 Runner 强制升级后怎么排查：2.329.0 注册门槛与 30 天规则

如果团队的 GitHub Actions 任务突然长时间排队，或者新机器执行 ./config.sh 时无法注册，先别急着改 workflow。GitHub 正在恢复自托管 Runner 的版本强制检查：2.329.0 是注册和重新注册的最低版本，已经在线的 Runner 还要跟上后续版本，不能把 2.329.0 当成永久免检版本。

这次变更到底卡住了哪一个环节

GitHub 这次给出了两个很容易搞混的版本校验规则。第一条是配置或者重新注册时，Runner 版本必须达到 2.329.0 或更高；第二条是已经在持续运行的实例，每个新的 Runner 正式版本发布后，要在 30 天内完成更新。第一条相当于入场资格校验，第二条相当于后续持续可用的通行证。

所以已经注册成功的旧机器不一定立刻在注册阶段报错，但它还是可能因为运行版本过旧，接不到新下发的 workflow 任务。GitHub 官方说明里也提到，涉及严重安全修复的更新不受 30 天宽限期保护，平台可能直接提前暂停旧版本的任务排队权限。

先按时间线判断自己是否已经进入风险区

你需要先确认自己组织所属的服务环境，不用直接套统一的时间节点。GitHub Enterprise Cloud 带数据驻留功能的版本，全面执行时间是 2026 年 7 月 31 日；普通 GitHub Enterprise Cloud 的全面执行时间是 2026 年 9 月 25 日。GitHub Enterprise Server 暂不在这次变更的影响范围内。

官方会在全面执行前安排灰度限流，先间歇性阻断旧版本注册，再逐步扩大到阻断任务执行。遇到“偶尔能注册、偶尔一直排队”的现象，要把对应时间点和 Runner 实际版本一起记录下来，不要看到一次注册成功就判定没有问题。

用一张清单盘点 Runner、镜像和注册脚本

盘点的时候要把 Runner 分成三层梳理：当前在线的运行实例、生成实例的底层模板、真正负责启动注册流程的自动化脚本。只在 GitHub 后台页面看在线列表，很容易漏掉暂时离线的 VM、Kubernetes 里生命周期很短的 Pod，以及下一次扩容操作会直接复用的旧镜像。

# 在 Runner 主机上确认本地版本
./run.sh --version

# 如果使用容器，检查镜像构建参数和启动日志
docker image inspect your-runner-image --format '{{.Id}}'
docker logs your-runner-container | tail -n 50

上面的命令只是定位排查的入口，实际运行参数要和你正在使用的 Runner 安装包、容器镜像配置对应。更稳妥的方式是把版本信息纳入发布清单字段，逐一记录主机名、所属 Runner 组、操作系统版本、当前 Runner 版本、自动更新开关状态和最近一次成功接任务的时间。

企业环境还可以查询审计日志里的 org.register_self_hosted_runner、repo.register_self_hosted_runner 或 enterprise.register_self_hosted_runner 事件。这类事件会记录注册时的 Runner 版本，但不能代替完整的资产盘点：只靠注册事件看不到所有当前已经连接平台的 Runner 实例。

升级时先改来源，再改运行实例

升级顺序建议固定为“来源—实例—任务”。先更新安装脚本、VM 镜像、容器镜像和 ARC 自定义镜像，再滚动替换实际运行的 Runner 实例，最后用一条最小 workflow 验证标签、权限和依赖工具链的完整性。这样可以避免刚升级完个别实例，旧模板又自动扩容出过期版本的实例。

1. 从 GitHub Actions Runner releases 页面确认当前可用的正式版本，不要写死一个长期不变的版本号在配置里。
2. 更新 VM 镜像、容器构建文件和初始化脚本；关闭自动更新的环境要明确标注下一次版本更新的责任人。
3. 先替换一台非核心业务的 Runner，验证它能正常注册、能进入目标 Runner 组，并且可以接到下发的测试任务。
4. 按批次轮换剩余的运行实例，不要一次性清空整个 Runner 组的所有机器。
5. 在版本管理清单里记录升级后的版本和操作时间，作为下一个 30 天更新窗口的计算起点。

如果 Runner 是从旧缓存镜像或者旧模板创建的，单独在当前机器执行一次更新，只能解决单个实例的版本问题。底层模板也必须同步重建，否则下一次自动扩容操作仍然会把过期版本带回来。

用最小 workflow 验证“能注册”不等于“能工作”

升级完成后，至少要验证四件事：Runner 状态是否正常在线、预设的标签是否匹配、工作流是否能正常启动、工作流依赖的工具链是否完整可用。版本升级可能同步伴随操作系统镜像的变动，不能只看到 Runner 在后台页面显示在线就判定升级完成。

name: runner-smoke-check
on: workflow_dispatch
jobs:
  check:
    runs-on: [self-hosted, linux, x64]
    steps:
      - name: Show environment
        run: |
          uname -a
          git --version
          python3 --version
      - name: Write result
        run: echo "runner smoke check passed"

检查结果要和业务 workflow 的真实需求做对照。比如负责构建 Java 项目的 Runner 还要确认 JDK 与 Maven 版本正常，构建前端项目的 Runner 要确认 Node.js 与对应包管理器可用。如果只跑一个空任务做验证，很可能漏掉镜像更新带来的工具缺失问题。

常见问题：几个容易误判的边界问题

2.329.0 是不是以后一直够用？

不是。它只是新架构识别 Runner 并允许注册或重新注册的最低版本，不是永久有效的运行版本。持续接收任务还要跟进官方后续的新版本，超过 30 天没有更新可能直接被平台停止排队权限。

自动更新开启后还需要定期盘点吗？

需要。自动更新功能依赖 Runner 实例能正常访问官方更新服务；网络出口规则、代理配置、内部镜像同步策略或者权限异常，都可能让版本停在旧版本状态。盘点结果要以实例上的实际版本为准。

GitHub Enterprise Server 也必须按这个日期升级吗？

这份 GitHub.com 发布的变更公告明确覆盖的是 GitHub.com 平台，包括 GitHub Enterprise Cloud；公告发布时 GitHub Enterprise Server 不在影响范围内。GHES 用户还是要结合自己安装版本的官方升级说明做判断。

为什么任务没有报错，只是一直排队？

旧 Runner 可能页面上仍显示在线，但实际已经不满足运行版本条件，或者 workflow 配置的标签找不到符合要求的实例。先核对 Runner 版本、标签配置、最近接单时间和任务日志，再判断是版本问题还是资源容量不足的问题。

把一次临时升级变成持续的版本管理

这次公告其实提醒所有团队，自托管 Runner 不应该被当成“一次安装、长期不动”的基础设施。把版本信息、镜像来源、自动更新状态和最近一次冒烟测试结果纳入发布清单；每周巡检版本漂移情况，每月验证扩容模板有效性，遇到紧急安全更新就缩短对应的检查窗口。这样就算下一次平台的强制校验规则继续调整，CI 服务的风险也能在任务排队之前就提前发现。