glab-runner

glab runner

Manage GitLab CI/CD runners from the command line.

List totals and pagination

glab runner list and glab runner jobs use the API-reported total in their text headers when available, separate from the number of returned rows. Missing totals must not be treated as proof there are no other pages. JSON contains the requested page's items, not every item counted by the header. Use --page and --per-page to traverse results explicitly; do not equate JSON array length with the server total.

Quick Start

# 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>

Common Workflows

List Runners

# 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

Sample JSON output parsing:

# 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')}")
"

Pause or Resume a Runner

Pausing a runner prevents it from picking up new jobs without removing it.

# 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

When to pause:

• Maintenance window (updates, reboots)
• Investigating a failing runner
• Temporarily reducing runner capacity
• Before decommissioning (verify no jobs are running first)

Note: Older docs/examples may mention glab runner pause, but the supported command surface uses glab runner update --pause / --unpause.