glab runner

Manage GitLab CI/CD runners from the command line.

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.

Inspect Jobs Processed by a 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

Useful for checking whether a runner is currently busy before pausing or deleting it.

Inspect Runner Managers

# List managers attached to a runner
glab runner managers 9

# JSON output
glab runner managers 9 --output json

Use this when you need to understand which runner manager processes/backends are associated with a runner.

Delete a 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

⚠️ Deletion is permanent. Pause first if unsure.

Decision Tree: Pause vs Delete

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 Status Reference

Troubleshooting

"runner: command not found":

• Requires a current glab release. Check with glab version.

"Permission denied" on instance-level runners:

• Instance-level runner management requires GitLab admin privileges.
• Project runners can be managed by project maintainers.

Runner won't pause or unpause:

• Verify runner ID with glab runner list.
• Check permissions (must be at least Maintainer on the project).
• Use glab runner update <id> --pause or --unpause.

Runner stuck "online" after pause:

• The runner process is still running on the host — it just won't accept new jobs.
• This is expected. To fully stop, SSH into the runner host and stop the process.

Cannot delete runner:

• Runner may be shared/group-level (requires higher privileges).
• Check if runner is assigned to multiple projects; removing from one project may require project-level deletion vs instance-level.

Assign / Unassign Runners to Projects

Assign an existing runner to a project so it can pick up jobs:

# 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

Remove a runner from a project (does not delete the runner):

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

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

Note: Assigning/unassigning requires at least Maintainer role on the project. This is different from glab runner delete which permanently removes the runner.

Related Skills

• glab-runner-controller — Manage runner controllers and orchestration (admin-only, experimental)
• glab-ci — View and manage CI/CD pipelines and jobs
• glab-job — Retry, cancel, trace logs for individual jobs

Command Reference

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