haomingz glab-runner-controller
管理 GitLab Runner 控制器及其认证令牌。
⚠️ 实验性功能
状态： 实验性（仅管理员可用）
- 此功能可能在没有事先通知的情况下被破坏或移除
- 使用风险自担
- 需要 GitLab 管理员权限
- 参阅：https://docs.gitlab.com/policy/development_stages_support/
功能说明
Runner 控制器用于管理基础设施中 GitLab Runner 的编排。此技能提供以下命令：
- 创建和配置 Runner 控制器
- 管理控制器生命周期（列出、更新、删除）
- 生成和轮换认证令牌
- 撤销已泄露的令牌
常见工作流
创建 Runner 控制器
# 使用默认设置创建
glab runner-controller create
# 创建时添加描述
glab runner-controller create --description "Production runners"
# 创建已启用的控制器
glab runner-controller create --description "Prod" --state enabled
状态说明：
disabled- 控制器已创建但未激活enabled- 控制器已激活（默认）dry_run- 测试模式（不实际执行 Runner）
列出和查看控制器
# 列出所有控制器
glab runner-controller list
# 分页列出
glab runner-controller list --page 2 --per-page 50
# 以 JSON 格式输出
glab runner-controller list --output json
更新控制器
# 更新描述
glab runner-controller update 42 --description "Updated name"
# 更改状态
glab runner-controller update 42 --state disabled
# 同时更新描述和状态
glab runner-controller update 42 --description "Prod" --state enabled
删除控制器
# 删除（会有确认提示）
glab runner-controller delete 42
# 跳过确认直接删除
glab runner-controller delete 42 --force
令牌管理工作流
令牌生命周期
创建 → 轮换 → 撤销 是安全最佳实践中的典型令牌生命周期。
1. 创建令牌
# 为控制器 42 创建令牌
glab runner-controller token create 42
# 创建时添加描述
glab runner-controller token create 42 --description "production"
# 以 JSON 格式输出（便于自动化）
glab runner-controller token create 42 --output json
重要： 令牌值创建后只显示一次，请立即保存。
2. 列出令牌
# 列出控制器 42 的所有令牌
glab runner-controller token list 42
# 以 JSON 格式列出
glab runner-controller token list 42 --output json
# 分页查看
glab runner-controller token list 42 --page 1 --per-page 20
3. 轮换令牌
轮换操作会生成新令牌并使旧令牌失效。
# 轮换令牌 1（带确认提示）
glab runner-controller token rotate 42 1
# 跳过确认直接轮换
glab runner-controller token rotate 42 1 --force
# 轮换并以 JSON 格式输出
glab runner-controller token rotate 42 1 --force --output json
适用场景：
- 定期轮换（满足安全策略要求）
- 令牌泄露后的响应
- 员工离职前的密钥轮换
4. 撤销令牌
# 撤销令牌 1（带确认提示）
glab runner-controller token revoke 42 1
# 跳过确认直接撤销
glab runner-controller token revoke 42 1 --force
适合撤销的场景：
- 令牌被泄露或泄漏
- 控制器已退役
- 不再需要访问权限
令牌安全最佳实践
- 定期轮换 - 设置定时轮换计划（如每 90 天）
- 使用描述信息 - 记录令牌用途和负责人
- 泄露后立即撤销
- 切勿将令牌提交到版本控制系统
- 使用
--output json进行自动化操作（安全地解析令牌值）
决策树：控制器状态选择
是否需要激活控制器？
├─ 是 → --state enabled
├─ 正在测试配置？ → --state dry_run
└─ 否（维护/设置阶段） → --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（需要 v1.83.0+） - 检查 GitLab 实例上是否启用了该功能标志
- 确认 GitLab 实例版本支持 Runner 控制器
分页不起作用：
- 默认每页 30 条
- 使用
--per-page调整（最大值因实例而异） - 使用
--page翻页浏览结果
v1.87.0 变更：Runner 范围子命令
从 v1.87.0 起，Runner 控制器支持 runner 范围，用于管理与控制器关联的 Runner。
列出范围内的 Runner
# 列出控制器 42 管理的所有 Runner
glab runner-controller runner list 42
# 以 JSON 格式输出
glab runner-controller runner list 42 --output json
# 分页查看
glab runner-controller runner list 42 --page 2 --per-page 50
将 Runner 添加到范围
# 将 Runner 添加到控制器 42 的范围
glab runner-controller runner create 42 --runner-id <runner-id>
从范围中移除 Runner
# 从控制器 42 的范围中移除 Runner（带确认提示）
glab runner-controller runner delete 42 <runner-id>
# 跳过确认直接移除
glab runner-controller runner delete 42 <runner-id> --force
使用场景： Runner 范围管理允许你明确定义哪些 Runner 由特定控制器编排，在多控制器环境中提供细粒度的 Runner 分配控制。
相关技能
CI/CD 与 Runner：
glab-ci- 查看和管理 CI/CD 流水线与作业glab-job- 重试、取消、查看单个作业的日志glab-runner- 管理单个 Runner（列出、暂停、删除）——v1.87.0 新增
仓库管理：
glab-repo- 管理仓库（Runner 控制器为实例级别）
认证：
glab-auth- 登录和认证管理
命令参考
完整的命令语法和所有可用参数，请参阅：
- references/commands.md