GitHub Actions "Waiting for a runner to pick up this job" 问题解决指南

问题描述

在使用 GitHub Actions 时，你可能会遇到工作流长时间停留在"Waiting for a runner to pick up this job"状态的情况。这表示 GitHub Actions 正在等待可用的 Runner（运行器）来执行你的任务，但由于某种原因无法分配到一个 Runner。

Runner 是什么？

Runner 是执行 GitHub Actions 工作流中任务的机器/环境。它可以：

• 克隆你的代码仓库
• 安装所需的软件环境
• 执行你定义的命令和脚本

Runner 分为两种类型：

Runner 类型

• GitHub-hosted runner：GitHub 托管的运行器

  • 由 GitHub 管理和维护
  • 无需用户设置
  • 使用预配置的软件环境
  • 无法直接访问本地资源

• Self-hosted runner：自托管运行器

  • 运行在你的服务器或本地环境
  • 可自定义软件环境和配置
  • 可以访问本地资源
  • 需要用户自行设置和维护

常见原因及解决方案

1. 使用了已弃用的操作系统标签

GitHub 会定期淘汰旧的操作系统版本。使用已弃用的 runs-on 标签会导致无法找到对应的运行器。

重要提醒

截至 2025 年 4 月 1 日，以下配置将不再工作：

runs-on: ubuntu-20.04

解决方案： 使用当前支持的标签：

runs-on: ubuntu-latest

参考 GitHub 官方文档获取最新支持的运行器列表。

2. 标签拼写错误

最常见的错误是 runs-on 后面的标签拼写错误，GitHub 不会提示错误，只会无限等待。

解决方案： 检查并修正拼写错误：

# 正确
runs-on: ubuntu-latest

# 错误示例
runs-on: ubuntu-latest   # 多余空格
runs-on: ubunut-latest   # 拼写错误

3. 运行器配置问题

对于自托管运行器，可能出现以下问题：

• 运行器未正确注册到 GitHub
• 运行器处于离线状态
• 权限配置不正确

解决方案：

• 检查运行器状态并重新注册
• 重启运行器服务：

# 停止运行器
./svc.sh stop

# 启动运行器
./svc.sh start

• 确保仓库有权使用组织级别的运行器

4. GitHub 服务状态问题

有时问题不在你的配置，而是 GitHub 平台本身的临时问题。

解决方案：

• 检查 GitHub 状态页面
• 取消并重新运行工作流（简单的"重启"操作）

5. 工作流语法错误

YAML 格式错误或缩进问题可能导致工作流无法正确解析。

解决方案：

• 使用 YAML 验证工具检查语法
• 确保正确的缩进（通常 2 个空格）
• 检查是否有缺少的必要步骤，如：

steps:
  - uses: actions/checkout@v3  # 必须有此步骤来获取代码

6. 环境配置冲突

某些环境配置可能导致阻塞问题。

解决方案： 如果使用了 environment 配置且出现问题，尝试暂时移除：

# 可能引起问题的配置
environment: production

# 暂时移除以测试
# environment: production

故障排除流程图

最佳实践建议

1. 始终使用最新标签：优先使用 ubuntu-latest 而非特定版本
2. 定期检查文档：关注 GitHub 官方公告关于运行器淘汰的信息
3. 验证工作流语法：使用 GitHub Actions 编辑器或 YAML 验证工具
4. 监控运行器状态：定期检查自托管运行器的连接状态
5. 设置超时限制：为作业设置超时避免无限等待

jobs:
  your-job:
    timeout-minutes: 30
    runs-on: ubuntu-latest
    steps:
      # ...

通过以上方法，你应该能够解决大多数"Waiting for a runner to pick up this job"的问题。如果问题仍然存在，建议查看 GitHub 社区论坛或联系 GitHub 支持。