glab-runner

glab runner

通过命令行管理 GitLab CI/CD Runner（运行器）。

glab v1.87.0 新增

快速入门

# 列出当前项目的 Runner
glab runner list

# 暂停一个 Runner
glab runner pause <runner-id>

# 删除一个 Runner
glab runner delete <runner-id>

常见工作流

列出 Runner

# 列出当前项目的所有 Runner
glab runner list

# 列出指定项目的 Runner
glab runner list --repo owner/project

# 列出所有 Runner（实例级别，仅管理员可用）
glab runner list --all

# 以 JSON 格式输出
glab runner list --output json

# 分页查看
glab runner list --page 2 --per-page 50

JSON 输出解析示例：

# 查找所有已暂停的 Runner
glab runner list --output json | python3 -c "
import sys, json
runners = json.load(sys.stdin)
paused = [r for r in runners if r.get('paused')]
for r in paused:
    print(f\"{r['id']}: {r.get('description','(no description)')} — {r.get('status')}\")
"

暂停 Runner

暂停 Runner 可以阻止它接收新作业，但不会将其移除。

# 暂停 Runner 123
glab runner pause 123

# 在指定项目上下文中暂停
glab runner pause 123 --repo owner/project

适合暂停的场景：

• 维护窗口期（更新、重启）
• 排查故障 Runner
• 临时减少 Runner 容量
• 退役前（先确认没有正在运行的作业）

删除 Runner

# 删除（会有确认提示）
glab runner delete 123

# 跳过确认直接删除
glab runner delete 123 --force

# 在指定项目上下文中删除
glab runner delete 123 --repo owner/project

⚠️ 删除操作不可恢复。 如果不确定，请先暂停。

决策树：暂停 vs 删除

是否需要永久移除该 Runner？
├─ 否 → 暂停它（可恢复）
└─ 是 → 它当前是否正在运行作业？
          ├─ 是 → 先暂停，等作业完成后再删除
          └─ 否 → 使用 --force 直接删除

Runner 状态参考

状态	含义
online	已连接，准备接收作业
offline	未连接（检查 Runner 进程）
paused	已连接但不接收新作业
stale	最近 3 个月无通信

故障排查

"runner: command not found"：

• 需要 glab v1.87.0 或更高版本。使用 glab version 检查。

实例级别 Runner 出现 "Permission denied"：

• 实例级别的 Runner 管理需要 GitLab 管理员权限。
• 项目 Runner 可以由项目维护者管理。

Runner 无法暂停：

• 使用 glab runner list 确认 Runner ID。
• 检查权限（至少需要项目的 Maintainer 角色）。

暂停后 Runner 仍显示 "online"：

• Runner 进程仍在主机上运行——只是不再接收新作业。
• 这是正常现象。如需完全停止，请通过 SSH 登录 Runner 主机并停止进程。

无法删除 Runner：

• Runner 可能是共享/群组级别的（需要更高权限）。
• 检查 Runner 是否被分配给多个项目；从一个项目移除可能需要项目级别删除而非实例级别删除。

为项目分配/取消分配 Runner（v1.88.0+）