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.
How do I install this agent skill?
npx skills add https://github.com/vince-winkintel/gitlab-cli-skills --skill glab-runner-controllerIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides documentation and command references for managing GitLab runner controllers and tokens using the 'glab' CLI. It is intended for GitLab administrators and does not contain any malicious scripts or data exfiltration patterns.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
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
# 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 inactiveenabled- Controller is active (default)dry_run- Test mode (no actual runner execution)
List and View Controllers
# 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
# 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
# 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
# List all scopes for controller 42
glab runner-controller scope list 42
# JSON output
glab runner-controller scope list 42 --output json
Add Scopes
# 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
# 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 isglab runner-controller scope ...plusglab runner-controller get.
Token Management Workflows
Token Lifecycle
Create → Rotate → Revoke is the typical token lifecycle for security best practices.
1. Create Token
# 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
# 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.
# 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
# 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
- Rotate regularly - Set up scheduled rotation (e.g., every 90 days)
- Use descriptions - Track token purpose and owner
- Revoke immediately when compromised
- Never commit tokens to version control
- Use
--output jsonfor 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 statusto 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
--forceto 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 jobsglab-job- Retry, cancel, view logs for individual jobsglab-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:
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/vince-winkintel/gitlab-cli-skills/glab-runner-controller">View glab-runner-controller on skillZs</a>