glab-runner — Claude Code skill: GitLab runner management
glab-runner is a Claude Code skill for managing GitLab CI/CD runners through glab: inspect jobs, assign runners to projects, pause them, or remove them.
MIT 129 installs ★ 51 updated 2026-10-20
npx skills add vince-winkintel/gitlab-cli-skills --skill glab-runner -a claude-codeWhat glab-runner does
This skill covers glab runner commands for project, group, and instance scopes. Use it to list runners and check their status, attach one to a project or unassign it, and inspect its jobs or manager processes. Runner lists and job results can be returned as JSON and browsed by page.
Pausing with glab runner update --pause stops a runner from accepting new jobs; it does not stop the process on its host. Deletion is permanent. Instance-level management requires GitLab administrator privileges, while assigning or unassigning a runner requires the Maintainer role on the project. Check for active jobs before deleting a runner, since its process can still be running.
What it helps with
- list runners for a project or group
- attach a runner to a project or unassign it
- inspect jobs handled by a runner
- pause a runner without deleting it
- remove a decommissioned runner
Example prompts for the agent
- List runners for the current project and return JSON.
- Check the jobs for runner
123, then pause it. - Assign runner
123to projectowner/project.
How to install glab-runner
1Skills CLI (Vercel)
npx skills add vince-winkintel/gitlab-cli-skills --skill glab-runner -a claude-code2Manually: put the files in place
~/.claude/skills/glab-runner/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/glab-runner/
1Skills CLI (Vercel)
npx skills add vince-winkintel/gitlab-cli-skills --skill glab-runner -a codex2Manually: put the files in place
.agents/skills/glab-runner/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add vince-winkintel/gitlab-cli-skills --skill glab-runner -a cursor2Manually: put the files in place
.cursor/skills/glab-runner/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install vince-winkintel/gitlab-cli-skills glab-runner2Manually: put the files in place
.github/skills/glab-runner/SKILL.md1Skills CLI (Vercel)
npx skills add vince-winkintel/gitlab-cli-skills --skill glab-runner -a gemini-cli2Platform CLI
gemini skills install https://github.com/vince-winkintel/gitlab-cli-skills --path glab-runnerManually: put the files in place
.devin/skills/glab-runner/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add vince-winkintel/gitlab-cli-skills --skill glab-runner -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about glab-runner
How do I install glab-runner in Claude Code?
Run npx skills add vince-winkintel/gitlab-cli-skills --skill glab-runner -a claude-code. The skill file is installed at ~/.claude/skills/glab-runner/SKILL.md.
What does glab-runner do?
It guides glab runner workflows for listing runners, checking jobs and managers, assigning runners to projects, pausing them, and deleting them.
Does pausing a runner stop its process?
No. glab runner update --pause prevents the runner from taking new jobs, but leaves its host process running.
Source text
SKILL.md · MIT
---
name: glab-runner
description: Manage GitLab CI/CD runners — list, assign, unassign, inspect recent jobs and managers, pause/unpause via update, and delete runners at project, group, or instance level. Use when viewing runner status, assigning runners to projects, checking what jobs a runner handled, seeing manager processes, temporarily pausing a runner, or removing a decommissioned runner. Triggers on runner, glab runner, list runners, assign runner, unassign runner, runner jobs, runner managers, pause runner, unpause runner, delete runner, CI 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
```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
Authored command summary; complete live help is linked below.
```
glab runner <command> [--flags]
Commands:
assign Assign a runner to a project
delete Delete a runner
jobs List jobs processed by a runner
list List runners for a project (default), group, or instance
managers List runner managers
unassign Unassign a runner from a project
update Update runner settings, including pause/unpause
Flags (list):
-g, --group List runners for a group (exclusive with --repo/--instance)
--jq Filter JSON output using a jq expression
--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
```
Use only one of `--group`, `--repo`, or `--instance`. The command enforces mutual exclusion even though the captured help describes `--group` as ignored with `--repo`.
See [references/commands.md](references/commands.md) for complete parent, list, and jobs help.
© vince-winkintel · MIT · vince-winkintel/gitlab-cli-skills