gitlab-cli-skills

GitLab CLI 技能

全面的 GitLab CLI (glab) 命令参考和工作流。

快速开始

# First time setup
glab auth login

# Common operations
glab mr create --fill              # Create MR from current branch
glab issue create                  # Create issue
glab ci view                       # View pipeline status
glab repo view --web              # Open repo in browser

多 Agent 身份说明

如果希望不同 Agent 显示为不同的 GitLab 用户，请为每个 Agent 分配独立的 GitLab 机器人／服务账号。同一 GitLab 用户下的多个个人访问令牌仍会显示为同一个身份。

对于由执行者撰写的 GitLab 评论、回复、审批及其他写入操作，请使用执行者身份。仅当 GitLab 操作明确属于某个 Agent 自身的工作成果时，才使用Agent 身份。请在首次写入 GitLab 之前确定要显示的执行者身份。

默认情况下，应将 shell 身份视为会持续生效且不安全。如果在同一 shell／会话中之前加载过其他环境文件，除非先主动切换并验证身份，否则 glab 可能仍会使用先前加载的身份进行写入。

一种实用做法是为每个执行者分别准备一个环境文件，例如 ~/.config/openclaw/env/gitlab-actor.env、~/.config/openclaw/env/gitlab-reviewer.env 和 ~/.config/openclaw/env/gitlab-release.env。请将这些环境文件保存在版本控制之外，限制其权限（例如 chmod 600），注意备份可能造成的暴露风险，并遵循最小权限原则使用机器人／服务账号令牌。在重复使用的 shell 中，先清除过期的 GitLab 身份验证变量，或启动新的 shell。如果这些文件使用普通的 KEY=value 行，请在运行 glab 前加载并导出变量：

unset GITLAB_TOKEN GITLAB_ACCESS_TOKEN OAUTH_TOKEN GITLAB_HOST
set -a
source ~/.config/openclaw/env/gitlab-<actor>.env
set +a

普通的 source 会更新当前 shell，但不一定会将变量导出到 glab 等子进程。如果令牌／主机变量未导出，glab 可能会静默回退到当前全局 glab 配置文件中保存的共享身份验证信息，从而导致操作显示为由错误账号执行。

任何 GitLab 写入操作前的必需预检

在任何 GitLab 写入操作前立即运行，包括 glab mr note、评审回复／审批，以及任何 glab api POST／PATCH／PUT／DELETE 调用：

glab auth status --hostname "$GITLAB_HOST"
glab api --hostname "$GITLAB_HOST" user

这假设目标执行者的环境文件已将 GITLAB_HOST 设置为你打算修改的确切 GitLab 实例。在两个命令都明确显示该主机上的目标显示身份之前，不要进行写入。

错误身份的补救措施

如果评论或回复是以错误身份发布的：

1. 停止发布。
2. 如需清理，删除发错身份的评论或回复。
3. 执行 unset GITLAB_TOKEN GITLAB_ACCESS_TOKEN OAUTH_TOKEN GITLAB_HOST，或启动新的 shell。
4. 使用 set -a; source ...; set +a 加载正确的环境文件。
5. 重新运行 glab auth status --hostname "$GITLAB_HOST" 和 glab api --hostname "$GITLAB_HOST" user。
6. 以正确的执行者身份重新发布。
7. 验证替换消息的讨论串中不再显示错误的作者身份。

如果错误身份的写入操作更改了评论或回复以外的状态，不要认为清理评论的步骤已经足够。按上述方式重新进行身份验证，然后以正确的执行者身份和主机，使用与该写入操作相对应的 GitLab 撤销操作，例如取消 MR 审批，或针对已更改的确切资源发送补偿性 glab api --hostname "$GITLAB_HOST" 修改请求。

技能组织

此技能会根据 GitLab 领域转至专门的子技能。每个子技能都位于同级目录中，是独立的技能；打开其 SKILL.md 查看完整详情。

核心工作流：

• glab-mr - 合并请求：创建、评审、审批、合并
• glab-issue - Issue：创建、列出、更新、关闭、评论
• glab-ci - CI/CD：流水线、作业、日志、制品
• glab-repo - 仓库：克隆、创建、派生、管理 项目管理：
• glab-milestone - 发布规划和里程碑跟踪
• glab-iteration - 冲刺/迭代管理
• glab-label - 标签管理和整理
• glab-release - 软件发布和版本控制
• glab-packages - 项目包注册表的列出、筛选和通用包上传

身份验证与配置：

• glab-auth - 登录、登出和 Docker 注册表身份验证
• glab-config - CLI 配置和默认设置
• glab-ssh-key - SSH 密钥管理
• glab-gpg-key - 用于提交签名的 GPG 密钥
• glab-token - 个人和项目访问令牌
• glab-todo - 个人 GitLab 待办事项的分类处理与完成

CI/CD 管理：

• glab-job - 单个作业操作
• glab-schedule - 定时流水线和 cron 作业
• glab-variable - CI/CD 变量和机密
• glab-securefile - 流水线安全文件
• glab-runner - Runner 管理：列出、分配/取消分配、检查作业/管理器、暂停/恢复、删除
• glab-runner-controller - Runner 控制器、范围和令牌管理（实验性，仅限管理员）

协作：

• glab-user - 用户个人资料和信息
• glab-snippet - 创建项目或个人代码片段
• glab-incident - 事件管理
• glab-workitems - 工作项：任务、OKR、关键结果、新一代史诗

高级：

• glab-api - 直接调用 REST API
• glab-artifact-registry - 实验性的短期 Artifact Registry 令牌交换和访问检查
• glab-cluster - Kubernetes 集群集成
• glab-container-registry - 容器注册表仓库和标签
• glab-dependency-firewall - 实验性的 Dependency Firewall 包检查、包管理器封装程序和本地活动摘要
• glab-deploy-key - 用于自动化的部署密钥
• glab-govern - 实验性的 AI Agent 治理钩子、诊断和会话记录审计同步
• glab-orbit - 用于远程图状态/查询/发现以及本地代码图索引/搜索的托管 Orbit CLI 工作流；使用 glab-skills 安装远程 Orbit 封装技能（实验性）
• glab-quick-actions - 用于批量更改状态的 GitLab 斜杠命令快捷操作
• glab-security - 项目安全扫描配置文件的启用/禁用/状态管理（实验性）
• glab-stack - 创建、重新排序、同步和删除本地堆叠/依赖合并请求元数据
• glab-opentofu - Terraform/OpenTofu 状态管理 实用工具：
• glab-alias - 自定义命令别名
• glab-completion - Shell 自动补全
• glab-help - 命令帮助和文档
• glab-version - 版本信息
• glab-check-update - 更新检查器
• glab-whatsnew - 自上次查看或升级后的基准版本以来的发行说明
• glab-changelog - 生成变更日志
• glab-attestation - 软件供应链安全
• glab-duo - GitLab Duo AI 助手
• glab-mcp - 已弃用的 glab MCP 兼容功能；新集成请使用 GitLab MCP Server
• glab-skills - 检查捆绑的技能；安装、列出和更新捆绑或精选的远程技能，包括 Orbit wrapper skill（实验性）

何时使用 glab，何时使用 Web UI

适合使用 glab 的场景：

• 在脚本中自动执行 GitLab 操作
• 使用以终端为中心的工作流
• 批量操作（多个 MR/Issue）
• 与其他 CLI 工具集成
• CI/CD 流水线工作流
• 无需在浏览器中切换上下文即可更快地导航

适合使用 Web UI 的场景：

• 通过内联评论进行复杂的差异审查
• 以可视化方式解决合并冲突
• 配置仓库设置和权限
• 跨项目进行高级搜索和筛选
• 查看安全扫描结果
• 管理群组/实例级设置

常见工作流

日常开发

# Start work on issue
glab issue view 123
git checkout -b 123-feature-name

# Create MR when ready
glab mr create --fill --draft

# Mark ready for review
glab mr update --ready

# Merge after approval
glab mr merge --when-pipeline-succeeds --remove-source-branch

代码审查

# List your review queue
glab mr list --reviewer=@me --state=opened

# Review an MR
glab mr checkout 456
glab mr diff
npm test

# Approve
glab mr approve 456
glab mr note 456 -m "LGTM! Nice work on the error handling."

CI/CD 调试

# Check pipeline status
glab ci status

# View failed jobs
glab ci view

# Get job logs
glab ci trace <job-id>

# Retry failed job
glab ci retry <job-id>

决策树

“应该先创建 MR，还是先处理 Issue？”

Need to track work?
├─ Yes → Create issue first (glab issue create)
│         Then: glab mr for <issue-id>
└─ No → Direct MR (glab mr create --fill)

适合使用 glab issue create + glab mr for 的场景：

• 编码前需要讨论或审批
• 跟踪功能请求或 Bug
• 冲刺规划和任务分配
• 希望 MR 合并时自动关闭 Issue

适合直接使用 glab mr create 的场景：

• 快速修复或更正拼写错误
• 基于现有 Issue 开展工作
• 热修复或紧急更改

“应该使用哪个 CI 命令？”

What do you need?
├─ Overall pipeline status → glab ci status
├─ Visual pipeline view → glab ci view
├─ Specific job logs → glab ci trace <job-id>
├─ Download build artifacts → glab ci artifact <ref> <job-name>
├─ Validate config file → glab ci lint
├─ Trigger new run → glab ci run
└─ List all pipelines → glab ci list

快速参考：

• 流水线级别：glab ci status、glab ci view、glab ci run
• 作业级别：glab ci trace、glab job retry、glab job view
• 构件：glab ci artifact（按流水线）或通过 glab job 获取作业构件

“克隆还是派生？”

What's your relationship to the repo?
├─ You have write access → glab repo clone group/project
├─ Contributing to someone else's project:
│   ├─ One-time contribution → glab repo fork + work + MR
│   └─ Ongoing contributions → glab repo fork, then sync regularly
└─ Just reading/exploring → glab repo clone (or view --web)

适合派生的场景：

• 你没有原始仓库的写入权限
• 为开源项目做贡献
• 希望在不影响原始仓库的情况下进行试验
• 需要自己的副本以便长期开展工作

适合克隆的场景：

• 你是有写入权限的项目成员
• 在组织/团队仓库中开展工作
• 不需要个人副本

“项目标签还是群组标签？”

Where should the label live?
├─ Used across multiple projects → glab label create --group <group>
└─ Specific to one project → glab label create (in project directory)

群组级标签：

• 在整个组织中统一使用标签
• 示例：priority::high、type::bug、status::blocked
• 由中央统一管理，并由项目继承

项目级标签：

• 项目专属工作流
• 示例：needs-ux-review、deploy-to-staging
• 由项目维护者管理

相关技能

MR 和 Issue 工作流：

• 从 glab-issue 开始，创建/跟踪工作
• 使用 glab-mr 创建可关闭 Issue 的 MR
• 脚本：scripts/create-mr-from-issue.sh 可自动执行此操作

CI/CD 调试：

• 使用 glab-ci 执行流水线级操作
• 使用 glab-job 执行单个作业操作
• 脚本：scripts/ci-debug.sh 可快速诊断故障

仓库操作：

• 使用 glab-repo 管理仓库
• 使用 glab-auth 设置身份验证
• 脚本：scripts/sync-fork.sh 可同步派生仓库

配置：

• 使用 glab-auth 进行初始身份验证
• 使用 glab-config 设置默认值和偏好
• 使用 glab-alias 设置自定义快捷方式