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+）

将已有的 Runner 分配给项目，使其可以接收作业：

# 将 Runner 分配给当前项目
glab runner assign <runner-id>

# 分配给指定项目
glab runner assign <runner-id> --repo owner/project

从项目中移除 Runner（不会删除该 Runner）：

# 从当前项目取消分配
glab runner unassign <runner-id>

# 从指定项目取消分配
glab runner unassign <runner-id> --repo owner/project

注意： 分配/取消分配 Runner 至少需要项目的 Maintainer 角色。这与 glab runner delete（永久删除 Runner）不同。

相关技能

• glab-runner-controller — 管理 Runner 控制器和编排（仅管理员，实验性功能）
• glab-ci — 查看和管理 CI/CD 流水线与作业
• glab-job — 重试、取消、追踪单个作业的日志

v1.88.0 变更

• 新增 glab runner assign <runner-id> — 将 Runner 分配给项目
• 新增 glab runner unassign <runner-id> — 从项目取消分配 Runner

命令参考

glab runner <command> [--flags]

Commands:
  list      Get a list of runners available to the user
  assign    Assign a runner to a project (v1.88.0+)
  unassign  Unassign a runner from a project (v1.88.0+)
  pause     Pause a runner
  delete    Delete a runner

Flags (list):
  --all          List all runners (instance-level, admin only)
  --output       Format output as: text, json
  --page         Page number
  --per-page     Number of items per page
  --repo         Select a repository
  -h, --help     Show help

Flags (pause / delete):
  --force        Skip confirmation prompt (delete only)
  --repo         Select a repository
  -h, --help     Show help