GitHub Actions 自托管 Mac Runner 版本过期怎么办？2026 修复指南

在修复前，先把“不能注册”和“不能执行工作流”作为两种不同故障处理。2.329.0 是 GitHub Enterprise Cloud 当前公告列出的注册或重新注册最低版本；执行任务所需的运行版本则会随新 Runner 版本推进，不是一个永久固定值。

生效日期与适用范围以开头引用的 GitHub 官方强制执行公告为准。即使某个 Runner 成功注册，也不能由此推断它仍在运行支持期内；同样，页面显示在线也只说明它连接着服务，不等于已经通过构建验收。

把仓库、组织和企业范围的 macOS Runner 放进同一份资产清单，至少记录版本、在线状态、忙闲状态、注册范围、标签、工作流用途、更新方式以及镜像或部署脚本来源。只看组织级页面容易漏掉仓库级节点；只看在线状态则无法识别版本已退役、标签路由错误或工具链损坏。

组织级 Runner 列表 API 返回 Runner 的 os、status、busy、version 和 labels 等字段；文档说明该接口每页最多返回 100 条，清点时须处理分页。仓库级节点应通过仓库对应的 Runner 列表接口补齐，不能把单一范围的结果当成全量机群。接口字段和权限要求见开头引用的自托管 Runner REST API 文档。

Runner 自动更新默认启用，但如果注册时使用 --disableupdate，升级责任就落到维护团队。还要把基础镜像、缓存模板、安装脚本和部署自动化列入清单：旧 Runner 可能不是从正在运行的节点恢复，而是在替换节点时被模板重新带回来。更新规则以开头引用的 GitHub 自托管 Runner 文档为准。

不要把 2.329.0 当成永久运行下限，也不要凭经验推算某个版本还能用到哪天。使用官方版本退役 API，针对资产清单里的具体版本查询注册和运行支持截止时间，再把结果关联到对应组织、仓库或部署模板。该接口用于提供特定 Runner 版本的退役计划；调用权限和响应字段见开头引用的官方 API 文档。

组织级请求的路径形式如下，使用有组织自托管 Runner 读取权限的令牌，并按组织实际配置管理令牌：

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  "https://api.github.com/orgs/<ORG>/actions/runners/deprecations/<VERSION>"

将响应中的版本和注册、运行退役日期保存到资产记录。若查询结果提示版本接近截止日期，先排入升级批次；若版本已过运行期限，则优先安排替代节点，并通过工作流确认队列和执行状态，而不是仅在资产表里改写“在线”。

升级前先找出谁真正控制 Runner 包版本。对自动更新节点，检查节点是否能访问更新服务并完成更新；对关闭自动更新的节点，指定维护责任人和发布节奏；对镜像或自动化创建的节点，更新源模板并重建验证。Runner 的最新版本可能按发布策略逐步开放，因此应核对实际适用环境的下载说明，而不是只复制某个版本号。

手动更新的触发条件不应只写成“版本过旧”。GitHub 文档要求禁用自动更新的 Runner 在新版本发布后 30 天内更新；任何版本发布都可能构成可用更新，关键安全更新还可能导致服务暂停向未更新 Runner 派发任务。相关维护要求见开头引用的自托管 Runner 更新文档。

不要同时替换整个构建池。先选择非关键节点作为试点，确认该节点能注册、接单并完成代表性工作流，再逐步处理承担生产任务的节点。GitHub 的管理文档支持通过标签或组将任务路由到指定 Runner；因此试点期间要检查工作流实际命中了哪个节点，而不只是看某台机器启动成功。注册范围、服务配置、标签和组管理方式，可参阅 GitHub 自托管 Runner 管理指南。

按以下顺序操作，避免把“更新成功”误判成“生产恢复”：

1. 标记关键度。按工作流用途区分非关键试点节点、普通构建节点和承担签名或发布任务的节点。
2. 检查更新通路。确认自动更新节点能访问更新服务；手动节点则核对下载包、安装来源和维护责任人。
3. 更新试点节点。先升级一台非关键 Mac Runner；镜像或自动化创建的节点还要用更新后的模板重建一次。
4. 检查注册与路由。确认节点在预期范围中注册，标签或 Runner 组符合工作流要求，并确认测试任务确实调度到试点节点。
5. 运行真实工作流。至少执行团队日常的 Mac CI Runner 任务，检查构建、测试和工作区清理；如果涉及签名或发布，另行验证对应权限与端到端任务。
6. 分批扩大范围。试点通过后，再逐批处理其余节点；如果任务排队、工具链异常或发布流程失败，暂停下一批。
7. 留存验收记录。记录升级前后版本、退役 API 查询结果、工作流运行结果、故障现象、处置人和回退结论。

排队本身也要结合状态判断：Runner 可能在线但忙碌，工作流也可能因标签或组匹配不到可用节点而无法调度。在线状态只代表连接状态，不能证明任务已成功执行；官方的监控与故障排查文档列有 Runner 状态与网络连通性检查方向。必要时使用 Runner 的 config 检查功能核验所需服务访问。

Mac Runner 版本太旧会停止执行工作流吗？

可能会。注册支持和运行支持是不同状态，已注册的旧节点也可能失去执行工作流的资格；需按版本查询运行退役日期，并用实际任务验证接单和执行，不要以在线标识代替验收。

2.329.0 是注册和执行任务的共同最低版本吗？

不是。该版本是公告中的注册或重新注册门槛。工作流执行门槛会动态变化，团队应结合版本退役 API 和当前官方更新规则判断，而不是长期固定到注册门槛。

关闭自动更新后怎么维护？

把版本更新纳入手动发布流程，指定负责人、更新窗口和回退条件，并同步修改镜像、缓存模板及安装自动化。按官方文档要求在新版本发布后 30 天内更新；关键安全更新还需留意可能暂停任务派发。

怎么查某个版本的退役日期？

使用组织级 Runner 版本退役 API 查询具体版本，检查响应中的注册与运行退役时间。把查询结果关联到节点资产并定期刷新；不要从在线状态、版本号大小或旧公告日期自行推断截止时间。

一次升级不能解决下一次版本退役。把 Runner 版本与 API 退役日期加入日常资产巡检，并为自动更新失败、更新服务不可达、工作流排队或执行失败指定责任人。镜像、安装脚本和自动化也要纳入变更审核；如果清点依赖 Runner 注册审计日志，还要注意审计事件反映的是注册活动，并非完整的在线资产清单。

✅ 建立按组织和仓库范围更新的 Runner 清单，明确每个节点的版本、用途和更新方式。
✅ 定期查询官方退役 API，将注册截止和运行截止分别告警。
✅ 镜像或部署模板变更时，检查重建节点是否仍带入旧版 Runner。
✅ 自动更新后抽查版本；手动维护节点则记录更新责任人与下一次复核安排。
✅ 以工作流运行记录作为恢复证据，分别保存普通构建、测试以及签名或发布任务的结果。
✅ 出现任务排队或失败时，按节点状态、标签路由、更新通路和工具链逐项定位，并记录回退条件。

如果团队现有方案依赖少量固定 Mac 构建机，版本升级窗口容易与日常 iOS CI/CD 任务争用容量；若另行采购实机，又要承担设备采购、闲置期间占用和持续维护的成本。对于只在迁移或高峰期需要额外 macOS 构建能力的团队，按需使用远程 Mac 可以作为临时容量选项，但它不能替代版本治理、Runner 权限审查或流水线验收。

先评估团队是否需要临时节点，再查看 NUKCLOUD 的远程 Mac 环境及套餐信息，核对接入方式与实际工作流是否匹配。若任务长期稳定、需要直接连接物理设备或必须完全控制本地硬件，优先评估自有 Mac；若只是升级期间补足构建容量，可先用真实工作流验证远程环境，再决定是否纳入弹性资源池。