Skip to content
Skills Library
DevOps & cloud · Tool integration

glab-runner-controller

/glab-runner-controller

Manage GitLab runner controllers and authentication tokens. Create, inspect, update, delete controllers; manage scopes; and generate, rotate, and revoke tokens. Admin-only experimental feature for managing runner controller lifecycle. Triggers on runner controller, controller token, controller scope, experimental runner, admin runner.

Licence
MIT
Last repository change
20.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 20.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Manage GitLab runner controllers and authentication tokens. Create, inspect, update, delete controllers; manage scopes; and generate, rotate, and revoke tokens. Admin-only experimental feature for managing runner controller lifecycle. Triggers on runner controller, controller token, controller scope, experimental runner, admin runner.

Original author description

Manage GitLab runner controllers and authentication tokens. Create, inspect, update, delete controllers; manage scopes; and generate, rotate, and revoke tokens. Admin-only experimental feature for managing runner controller lifecycle. Triggers on runner controller, controller token, controller scope, experimental runner, admin runner.

How it works

  1. ⚠️ Experimental Feature
  2. What It Does
  3. Common Workflows
  4. Scope Management
  5. Token Management Workflows
  6. Decision Tree: Controller State Selection
  7. Troubleshooting
  8. Related Skills
  9. Command Reference
Original SKILL.md headings · 260 lines, 983 words
SKILL.md preview
---
name: glab-runner-controller
description: Manage GitLab runner controllers and authentication tokens. Create, inspect, update, delete controllers; manage scopes; and generate, rotate, and revoke tokens. Admin-only experimental feature for managing runner controller lifecycle. Triggers on runner controller, controller token, controller scope, experimental runner, admin runner.
---

# glab-runner-controller

Manage GitLab runner controllers and their authentication tokens.

## ⚠️ Experimental Feature

**Status:** EXPERIMENTAL (Admin-only)
- This feature may be broken or removed without prior notice
- Use at your own risk
- Requires GitLab admin privileges
- See: https://docs.gitlab.com/policy/development_stages_support/

## What It Does

Runner controllers manage the orchestration of GitLab Runners in your infrastructure. This skill provides commands to:
- Create and configure runner controllers
- Inspect controller details and connection status
- Manage controller lifecycle (list, get, update, delete)
- Manage controller scopes (instance-level or runner-level)
- Generate and rotate authentication tokens
- Revoke compromised tokens

## Common Workflows

### Create Runner Controller

```bash
# Create with default settings
glab runner-controller create

# Create with description
glab runner-controller create --description "Production runners"

# Create enabled controller
glab runner-controller create --description "Prod" --state enabled
```

**States:**
- `disabled` - Controller exists but inactive
- `enabled` - Controller is active (default)
- `dry_run` - Test mode (no actual runner execution)

### List and View Controllers

```bash
# List all controllers
glab runner-controller list

# List with pagination
glab runner-controller list --page 2 --per-page 50

# Output as JSON
glab runner-controller list --output json

# Get one controller with status details
glab runner-controller get 42

glab runner-controller get 42 --output json
```

### Update Controller

```bash
# Update description
glab runner-controller update 42 --description "Updated name"

# Change state
glab runner-controller update 42 --state disabled

# Update both
glab runner-controller update 42 --description "Prod" --state enabled
```

### Delete Controller

```bash
# Delete with confirmation prompt
glab runner-controller delete 42

# Delete without confirmation
glab runner-controller delete 42 --force
```

## Scope Management

Runner controller scopes determine what the controller is allowed to evaluate.

### List Scopes

```bash
# List all scopes for controller 42
glab runner-controller scope list 42

# JSON output
glab runner-controller scope list 42 --output json
```

### Add Scopes

```bash
# Allow the controller to evaluate all instance runners
glab runner-controller scope create 42 --instance

# Allow the controller to evaluate a specific runner
glab runner-controller scope create 42 --runner 5

# Add multiple runner scopes
glab runner-controller scope create 42 --runner 5 --runner 10
glab runner-controller scope create 42 --runner 5,10
```

### Remove Scopes

```bash
# Remove the instance-level scope
glab runner-controller scope delete 42 --instance

# Remove a specific runner-level scope
glab runner-controller scope delete 42 --runner 5 --force
```

> **Note:** Older docs/examples may refer to `glab runner-controller runner ...` subcommands. The current user-facing surface is `glab runner-controller scope ...` plus `glab runner-controller get`.

## Token Management Workflows

### Token Lifecycle

**Create → Rotate → Revoke** is the typical token lifecycle for security best practices.

#### 1. Create Token

```bash
# Create token for controller 42
glab runner-controller token create 42

# Create with description
glab runner-controller token create 42 --description "production"

# Output as JSON (for automation)
glab runner-controller token create 42 --output json
```

**Important:** Save the token value immediately - it's only shown once at creation.

#### 2. List Tokens

```bash
# List all tokens for controller 42
glab runner-controller token list 42

# List as JSON
glab runner-controller token list 42 --output json

# Paginate
glab runner-controller token list 42 --page 1 --per-page 20
```

#### 3. Rotate Token

Rotation generates a new token and invalidates the old one.

```bash
# Rotate token 1 (with confirmation)
glab runner-controller token rotate 42 1

# Rotate without confirmation
glab runner-controller token rotate 42 1 --force

# Rotate and output as JSON
glab runner-controller token rotate 42 1 --force --output json
```

**Use cases:**
- Scheduled rotation (security policy compliance)
- Token compromise response
- Key rotation before employee departure

#### 4. Revoke Token

```bash
# Revoke token 1 (with confirmation)
glab runner-controller token revoke 42 1

# Revoke without confirmation
glab runner-controller token revoke 42 1 --force
```

**When to revoke:**
- Token compromised or leaked
- Controller decommissioned
- Access no longer needed

### Token Security Best Practices

1. **Rotate regularly** - Set up scheduled rotation (e.g., every 90 days)
2. **Use descriptions** - Track token purpose and owner
3. **Revoke immediately** when compromised
4. **Never commit tokens** to version control
5. **Use `--output json`** for automation (parse token value securely)

## Decision Tree: Controller State Selection

```
Do you need the controller active?
├─ Yes → --state enabled
├─ Testing configuration? → --state dry_run
└─ No (maintenance/setup) → --state disabled
```

## Troubleshooting

**"Permission denied" or "403 Forbidden":**
- Runner controller commands require GitLab admin privileges
- Verify you're authenticated as an admin user
- Check `glab auth status` to confirm current user

**"Runner controller not found":**
- Verify controller ID with `glab runner-controller list`
- Controller may have been deleted
- Check if you have access to the correct GitLab instance

**Token creation fails:**
- Ensure controller exists and is enabled
- Verify admin privileges
- Check GitLab instance version (experimental features may require recent versions)

**Token rotation shows old token still works:**
- Token invalidation may take a few seconds to propagate
- Wait 10-30 seconds and test again
- Check controller state (disabled controllers don't enforce token validation)

**Cannot delete controller:**
- Check if controller has active runners
- May need to decommission runners first
- Use `--force` to override (⚠️ destructive)

**Experimental feature not available:**
- Verify glab version: `glab version` (requires a recent glab build)
- Check if feature flag is enabled on GitLab instance
- Confirm GitLab instance version supports runner controllers

## Related Skills

**CI/CD & Runners:**
- `glab-ci` - View and manage CI/CD pipelines and jobs
- `glab-job` - Retry, cancel, view logs for individual jobs
- `glab-runner` - Manage individual runners (list, assign, jobs, managers, update, delete)

**Repository Management:**
- `glab-repo` - Manage repositories (runner controllers are instance-level)

**Authentication:**
- `glab-auth` - Login and authentication management

## Command Reference

For complete command syntax and all available flags, see:
- [references/commands.md](references/commands.md)
Files in this package (2)
  • SKILL.md 7 KB
  • references/commands.md 12 KB

Versions

RepositoryScoreLicence
This page · vince-winkintel/gitlab-cli-skills100MIT
serejaris/kimi-skills100MIT

Database snapshot: 13.11.2026 · package version e3087723e288 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100glab-runner
    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…
  • 100glab-runner
    Manage GitLab CI/CD runners — list, assign, unassign, pause, and delete runners at project, group, or instance level. Use when viewing runner status, assigning runners to projects, temporarily pausing a runner, or removing a decommissioned runner. Triggers on runner, glab…
  • 95glab-token
    Manage GitLab personal, project, and group access tokens, including explicitly approved self-rotation. Use when creating tokens, revoking access, or managing API authentication. Triggers on token, access token, PAT, personal access token, API token.
  • 100gitlab-cicd
    Use when creating, modifying, or debugging GitLab CI/CD pipelines on self-hosted GitLab instances — writing .gitlab-ci.yml files, managing GitLab Runners, using the glab CLI, automating GitLab API operations, debugging failed pipeline jobs, or setting up multi-environment…
  • 100github-runner
    Deploy, manage, and troubleshoot self-hosted GitHub Actions runners. Covers systemd service, Docker containers, Kubernetes (Actions Runner Controller), and the Scale Set Client. Use when setting up a CI runner, debugging registration failures, designing autoscaling, or hardening…
  • 95netalertx-authentication-tokens
    Manage and troubleshoot API tokens and authentication-related secrets. Use this when you need to find, rotate, verify, or debug authentication issues (401/403) in NetAlertX.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.