Glab Runner

glab runner

Manage GitLab CI/CD runners from the command line.

Added in glab v1.87.0

Quick Start

# List runners for current project
glab runner list

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

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

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

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

# Pause runner 123
glab runner pause 123

# Pause in a specific project context
glab runner pause 123 --repo 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)

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 → Pause first, wait for jobs to finish, then delete
          └─ No → Delete with --force

Runner Status Reference

Troubleshooting

"runner: command not found":

• Requires glab v1.87.0+. 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:

• Verify runner ID with glab runner list.
• Check permissions (must be at least Maintainer on the project).

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 (v1.88.0+)

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

v1.88.0 Changes

• Added glab runner assign <runner-id> — assign a runner to a project
• Added glab runner unassign <runner-id> — unassign a runner from a project

Command Reference

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