glab-runner

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