GitHub 官方说明:任务分配给 Runner 后,Runner 若在 60 秒内没有接手,任务会重新排队;这不等于 Runner 已离线。自托管 Runner 路由规则 因此,本周先记录任务状态和最近一次成功运行,再按“Runner 离线、在线但无匹配执行节点、任务已启动后失败”分流排查。标签或 Runner 组不匹配,先修配置;只有主机不可用、网络不稳定或维护能力不足时,才评估更换运行方式。
适合维护 GitHub Actions macOS 自托管 Runner、需要定位服务和连接问题的工程师。
如果 iOS 构建持续排队,可核对工作流标签与 Runner 状态是否对应。
如果你负责团队构建节点,可据故障根因决定修配置还是调整主机方案。
离线状态与排队任务:先分清症状
GitHub 将 Runner 状态显示为“离线”,表示它没有连接到 GitHub;可能原因包括主机关闭、Runner 应用未运行或应用无法通信。官方状态定义与排障入口 与此不同,任务排队可能只是当前没有满足 runs-on 条件的在线空闲 Runner。任务开始后再失败,则应从工作流步骤和 Runner 日志判断,不要仅凭失败结果重启主机。
先在仓库或组织的 Runner 设置页记下状态、标签和 Runner 组,再打开失败或排队的工作流,确认任务停在分配前、接手阶段,还是某个构建步骤。把这些现象与最近一次成功运行的时间、使用的工作流版本放在一起,才能避免把“排队”和“离线”当成同一种故障。
macOS Runner 排障:主机、网络与服务对照
建议按“机器是否可用 → Runner 进程是否运行 → GitHub 连接是否正常”的顺序检查。手动在终端启动 Runner 后能上线,只能说明交互式启动路径可用;它不能证明重启后 launchd 会按预期拉起服务。
| 观察到的现象 | 优先检查 | 判断方向 |
|---|---|---|
| 设置页显示离线 | 主机供电与联网、Runner 进程、连接检查 | 先确定是主机停机、服务停止还是出站连接失败 |
| Runner 在线但任务排队 | runs-on 标签、Runner 标签、Runner 组权限 |
全部匹配且有在线空闲节点,任务才有机会被分配 |
| 任务已接手后失败 | 工作流步骤、Runner 的 Worker_ 日志 |
区分构建脚本或环境错误与 Runner 接单故障 |
| 重启后反复离线 | svc.sh 状态、服务配置文件、启动账户 |
检查服务启动是否稳定,而不只看手动启动结果 |
网络检查与 Runner 诊断日志
在 Runner 安装目录执行官方连通性检查:
./config.sh --check --url https://github.com/ORG/REPO --pat YOUR_TOKEN
把 ORG/REPO 和令牌替换为实际值。该检查会逐项测试所需服务,并在终端报告通过或失败;失败项目的详细信息可从安装目录下的 _diag 日志中查找。GitHub 网络检查与日志说明
如果输出指向网络,继续核对防火墙、代理、DNS 解析以及到 GitHub 所需服务的出站 HTTPS 连接。GitHub 列出了 Runner 通信所需的域名和端口要求,实际放行范围还要结合你的工作流是否下载 Actions、使用制品或访问包服务来确认。自托管 Runner 通信要求 不要把关闭 TLS 证书校验当作常规修复;这会削弱连接验证,不能替代对代理证书或网络策略的正确排查。
网络日志只说明 Runner 到 GitHub 的通信情况,不一定能解释构建脚本为何失败。若任务已经开始,在工作流运行页面打开失败步骤;需要更多 Runner 层信息时,可启用 ACTIONS_RUNNER_DEBUG,然后下载运行日志中的诊断文件。Runner 诊断日志开启方法 工作流日志可显示任务在哪个步骤停止;本机 _diag 中以 Runner_ 开头的日志偏向 Runner 进程,以 Worker_ 开头的日志则对应具体任务。工作流运行日志查看方法
launchd Runner 服务与终端运行
检查 macOS 服务时,先进入 Runner 安装目录查看状态:
./svc.sh status
cat .service
svc.sh status 会通过 launchctl 检查服务;.service 文件可帮助你找到服务的配置路径。若服务状态没有显示运行,或服务在重启后没有恢复,继续核对服务安装情况、启动账户和相关日志。GitHub 的 macOS 排障文档也建议使用 launchctl 观察服务活动,并从 Runner 目录的服务文件确认服务名称。macOS launchd 排查说明
需要留意服务启动时使用的账户和你平时登录终端的账户可能不同。因此,交互式启动成功不能证明服务具备相同的环境变量、目录权限或工具路径。GitHub 文档说明,服务模式用于在机器启动时自动运行 Runner;若你使用自定义服务配置,应确保服务通过官方要求的入口启动。Runner 服务配置说明
在线但无人接单:标签与 Runner 组必须同时匹配
macOS Runner 在线但任务仍排队
检查工作流里的 runs-on,再与仓库或组织设置页展示的 Runner 标签逐项对照。多个标签是累积条件:任务要求 self-hosted、macOS 和某个自定义标签时,Runner 必须具备全部要求;如果还指定了 Runner 组,该组也必须允许此仓库使用。工作流标签与 Runner 组路由规则
例如,工作流要求一个自定义标签,但 Runner 上该标签已被删除,即使 Runner 显示在线,也无法接下这个任务。反过来,如果你误把架构或系统标签写进 runs-on,同样可能没有任何节点满足条件。修改前先从当前仓库的 Runner 页面复制实际标签,不要凭记忆重建配置;再确认 Runner 组是否授权该仓库访问。Runner 组访问权限说明
你可以先勾选核验这些项目,再决定是否重启服务:
- [ ] 设置页中的 Runner 状态为在线,且当前不是正在执行另一个任务。
- [ ] 工作流
runs-on的每个标签都能在目标 Runner 上找到。 - [ ] 工作流指定的 Runner 组与该 Runner 实际所属组一致。
- [ ] Runner 组的仓库访问策略允许当前仓库使用。
- [ ] 任务日志显示的是“等待匹配 Runner”,而不是已经进入构建步骤后失败。
- [ ] 网络检查、服务状态和诊断日志已与任务发生时间对齐。
如果只是标签或组权限不匹配,优先改正工作流或权限,不要迁移主机。任务路由依据当前仓库或组织的实际设置;重启一台标签仍不匹配的机器,并不会让任务自动找到它。
从配置修复到主机调整:按根因做决定
用下面的评分判断问题落在哪一层。评分描述的是排障优先级,不是 Runner 性能测试结果。
- 配置问题:高优先级。 在线节点未接单,但标签或组不匹配;先修
runs-on、Runner 标签或仓库访问策略。 - 服务问题:高优先级。 终端运行正常,服务状态异常或重启后失联;先修
launchd服务、启动账户和环境配置。 - 网络问题:高优先级。 连通性检查失败或日志提示无法联系 GitHub;先查 DNS、代理、防火墙和出站规则。
- 主机可用性问题:中到高优先级。 主机经常关机、网络不稳定或团队无法及时维护;再评估持续在线的 Mac 运行环境。
- 构建环境问题:先看任务日志。 任务已经开始,错误落在依赖安装、权限或项目脚本时,应先修构建环境,而不是直接更换硬件。
如果这些排查仍无法定位,建议按故障发生顺序保存工作流日志、_diag 相关文件、服务状态和网络检查结果;避免只保留一张“Runner 离线”的截图。把 Runner 的接单记录与失败步骤对齐,通常比反复重启更能区分连接故障和项目错误。
自管 Mac 的优势是你能直接维护硬件与系统环境,但主机断电或本地网络中断会让节点失联;服务配置、系统更新和日志留存也需要团队持续负责。远程 Mac 可以把持续在线的主机环境交由服务方案提供,但不能替你修复错误的标签、权限或 YAML。若根因确实是主机持续在线或运维能力不足,可先查看 VPSPull 的远程 Mac 环境说明 与 远程 Mac 连接选项,再按任务运行方式和团队维护能力评估是否迁移;如果问题只是工作流配置,先改配置才是更直接的修复。
