glab-runner-controller

glab-runner-controller

管理 GitLab Runner 控制器及其身份验证令牌。

⚠️ 实验性功能

状态： 实验性（仅限管理员）

• 此功能可能会出现故障或被移除，恕不另行通知
• 使用风险自负
• 需要 GitLab 管理员权限
• 参见：https://docs.gitlab.com/policy/development_stages_support/

功能说明

Runner 控制器负责管理基础设施中 GitLab Runner 的编排。此技能提供以下命令：

• 创建和配置 Runner 控制器
• 查看控制器详情和连接状态
• 管理控制器生命周期（列表、获取、更新、删除）
• 管理控制器作用域（实例级或 Runner 级）
• 生成和轮换身份验证令牌
• 撤销已泄露的令牌

常见工作流

创建 Runner 控制器

# 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

状态：

• disabled - 控制器已创建，但未启用
• enabled - 控制器处于启用状态（默认）
• dry_run - 测试模式（不实际运行 Runner）

列出和查看控制器

# 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 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 with confirmation prompt
glab runner-controller delete 42

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

作用域管理

Runner 控制器作用域决定了控制器可以评估的内容。

列出作用域

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

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

添加作用域

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

注意： 较早的文档／示例中可能会提到 glab runner-controller runner ... 子命令。当前面向用户的命令为 glab runner-controller scope ... 和 glab runner-controller get。

令牌管理工作流

令牌生命周期

遵循安全最佳实践时，典型的令牌生命周期为 创建 → 轮换 → 撤销。

1. 创建令牌

# 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

重要： 创建时请立即保存令牌值——它只会显示一次。

2. 列出令牌

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

适用场景：

• 定期轮换（符合安全策略要求）
• 响应令牌泄露事件
• 员工离职前轮换密钥

4. 撤销令牌

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

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

撤销时机：

• 令牌已泄露
• 控制器已停用
• 不再需要访问权限

令牌安全最佳实践

1. 定期轮换 - 设置定期轮换（例如每 90 天一次）
2. 使用描述信息 - 记录令牌用途和所有者
3. 令牌泄露时立即撤销
4. 切勿将令牌提交到版本控制系统
5. 自动化时使用 --output json（安全地解析令牌值）

决策树：选择控制器状态

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

故障排除

“Permission denied”或“403 Forbidden”：

• Runner 控制器命令需要 GitLab 管理员权限
• 确认你是以管理员用户身份进行身份验证
• 检查 glab auth status，确认当前用户

“Runner controller not found”：

• 使用 glab runner-controller list 确认控制器 ID
• 控制器可能已被删除
• 确认你有权访问正确的 GitLab 实例

令牌创建失败：

• 确保控制器存在且处于启用状态
• 确认拥有管理员权限
• 检查 GitLab 实例版本（实验性功能可能需要较新版本）

令牌轮换后旧令牌仍可用：

• 令牌失效可能需要几秒钟才能生效
• 等待 10-30 秒后再次测试
• 检查控制器状态（已禁用的控制器不会强制执行令牌验证）

无法删除控制器：

• 检查控制器是否有关联的活跃 Runner
• 可能需要先停用 Runner
• 使用 --force 强制执行（⚠️ 具有破坏性）

实验性功能不可用：

• 检查 glab 版本：glab version（需要较新的 glab 构建版本）
• 检查 GitLab 实例上是否启用了功能标志
• 确认 GitLab 实例版本支持 Runner 控制器

相关技能

CI/CD 与运行器：

• glab-ci - 查看和管理 CI/CD 流水线与作业
• glab-job - 重试、取消单个作业，查看其日志
• glab-runner - 管理单个运行器（列出、分配、作业、管理器、更新、删除）

仓库管理：

• glab-repo - 管理仓库（运行器控制器属于实例级别）

身份验证：

• glab-auth - 登录与身份验证管理

命令参考

完整的命令语法和所有可用标志，请参阅：

• references/commands.md