glab-runner

What this skill does

# glab runner

Manage GitLab CI/CD runners from the command line.

## Quick Start

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

```bash
# 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:**
```bash
# 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.

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

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

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

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

| Status | Meaning |
|---|---|
| `online` | Connected and ready to accept jobs |
| `offline` | Not connected (check runner process) |
| `paused` | Connected but not accepting new jobs |
| `stale` | No contact in the last 3 months |

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

```bash
# 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):

```bash
# 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):
  --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
```