glab-runner

glab runner

从命令行管理 GitLab CI/CD Runner。

快速入门

# List runners for current project
glab runner list

# Pause a runner
glab runner update <runner-id> --pause

# Delete a runner
glab runner delete <runner-id>

常见工作流

列出 Runner

# List all runners for current project
glab runner list

# List for a specific project
glab runner list --repo owner/project

# List all runners (instance-level, admin only)
glab runner list --instance

# Output as JSON
glab runner list --output json

# Paginate
glab runner list --page 2 --per-page 50

示例 JSON 输出解析：

# Find all paused runners
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 可阻止其接收新任务，但不会将其移除。

# Pause runner 123
glab runner update 123 --pause

# Resume a paused runner
glab runner update 123 --unpause

# Pause in a specific project context
glab runner update 123 --pause -R owner/project

暂停时机：

• 维护窗口（更新、重启）
• 排查故障 Runner
• 暂时减少 Runner 容量
• 停用之前（先确认没有任务正在运行）

注意： 较早的文档/示例可能会提到 glab runner pause，但当前支持的命令形式为 glab runner update --pause / --unpause。

检查 Runner 处理的任务

# List recent jobs for runner 9
glab runner jobs 9

# Show only running jobs
glab runner jobs 9 --status running

# JSON output for automation
glab runner jobs 9 --output json

在暂停或删除 Runner 前，可用它检查 Runner 当前是否繁忙。

检查 Runner 管理器

# List managers attached to a runner
glab runner managers 9

# JSON output
glab runner managers 9 --output json

需要了解与 Runner 关联的 Runner 管理器进程/后端时，请使用此命令。

删除 Runner

# Delete with confirmation prompt
glab runner delete 123

# Delete without confirmation
glab runner delete 123 --force

# Delete in a specific project context
glab runner delete 123 --repo owner/project

⚠️ 删除操作不可撤销。 不确定时请先暂停。

决策树：暂停还是删除

Do you need the runner gone permanently?
├─ No → Pause it (recoverable)
└─ Yes → Is it actively running jobs?
          ├─ Yes → Check `glab runner jobs <id>`, then pause first and wait for jobs to finish
          └─ No → Delete with --force

Runner 状态参考

状态	含义
online	已连接并准备好接收任务
offline	未连接（检查 Runner 进程）
paused	已连接，但不接收新任务
stale	最近 3 个月内未联系

故障排查

“runner: command not found”：

• 需要使用当前版本的 glab。使用 glab version 检查。

实例级 Runner 出现“Permission denied”：

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

无法暂停或恢复 Runner：

• 使用 glab runner list 确认 Runner ID。
• 检查权限（项目角色必须至少为 Maintainer）。
• 使用 glab runner update <id> --pause 或 --unpause。

暂停后 Runner 仍显示为“online”：

• Runner 进程仍在主机上运行，只是不再接收新任务。
• 这是预期行为。要完全停止 Runner，请通过 SSH 登录 Runner 主机并停止该进程。

无法删除 Runner：

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

将 Runner 分配给项目 / 从项目中取消分配

将现有 Runner 分配给项目，使其能够接收任务：

# Assign a runner to the current project
glab runner assign <runner-id>

# Assign to a specific project
glab runner assign <runner-id> --repo owner/project

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

# Unassign from current project
glab runner unassign <runner-id>

# Unassign from a specific project
glab runner unassign <runner-id> --repo owner/project

注意： 分配/取消分配需要至少具备项目 Maintainer 角色。这与 glab runner delete 不同，后者会永久移除 Runner。

相关技能

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

命令参考

glab runner <command> [--flags]

Commands:
  assign    Assign a runner to a project
  delete    Delete a runner
  jobs      List jobs processed by a runner
  list      Get a list of runners available to the user
  managers  List runner managers
  unassign  Unassign a runner from a project
  update    Update runner settings, including pause/unpause

Flags (list):
  --instance     List all runners available to the user (instance scope)
  --output       Format output as: text, json
  --page         Page number
  --per-page     Number of items per page
  --repo         Select a repository
  -h, --help     Show help