GitLab CLI（glab）技能

当用户需要从终端操作 GitLab 时，使用 glab。本文档中的说明已通过 glab 1.90.0 验证。

该高频路径有意保持精简：仅覆盖合并请求（MR）、议题（Issue）、CI/CD、仓库定位（repo targeting）、仓库查看/克隆/派生（repo view/clone/fork），以及 glab api。更广泛的项目管理操作应仅通过专用参考文件进行记录。

适用场景

当用户需要执行以下操作时，请调用此技能：

• 创建、评审、更新、合并或检查合并请求
• 创建、查看或更新议题
• 检查、触发、重试、取消或查看 CI/CD 流水线与作业
• 显式指定目标仓库，或查看、克隆、派生仓库
• 与自托管的 GitLab 实例交互
• 使用 glab api 直接调用 GitLab REST 或 GraphQL API

预检步骤

执行实际操作前，请运行以下检查命令：

glab --version
glab auth status
git remote -v

若当前不在 Git 仓库目录中，则不得猜测上下文。请改用以下任一模式：

glab mr list -R group/project
glab issue list -R group/project
glab repo view group/project
glab repo view https://gitlab.example.org/group/project.git

对于自托管 GitLab 实例，必要时需显式指定主机地址：

glab auth login --hostname gitlab.example.org
GITLAB_HOST=gitlab.example.org glab repo view group/project
glab api --hostname gitlab.example.org projects/:id

执行策略

• 优先使用只读命令：如 list、view、status、trace。
• 当用户需要过滤或自动化处理时，优先使用结构化输出格式：
  • 对 mr、ci 和 repo 命令使用 --output json
  • 对 issue list 使用 -O json
  • 对通过管道传给 jq 的大型 glab api --paginate 响应，使用 --output ndjson
• 执行远程变更操作前，须确认仓库、目标对象及分支。该要求适用于以下命令：mr create、mr merge、mr close、issue close、ci run、ci retry、ci cancel、ci delete 和 repo fork。
• 若 glab auth status 显示凭证缺失或无效，请立即中止并提示用户完成认证，而非重复调用失败的 API。
• 在不确定参数标志时，应先运行 glab --help。CLI 行为可能随版本更新而变化。
• 对于 glab api，分页参数应置于端点查询字符串中。示例如下：

glab api "projects/:id/jobs?per_page=100" --paginate --output ndjson

常用工作流

合并请求（MR）

glab mr list --reviewer=@me --output json
glab mr checkout 123
glab mr view 123 --comments
glab mr create -t "Add feature" -d "Implements X" --reviewer alice,bob -l feature
glab mr create --related-issue 123 --fill --yes
glab mr update 123 --ready
glab mr note 123 -m "Please add tests"
glab mr merge 123 --auto-merge

glab mr create --fill 会将 push 设为 true。使用 --fill --yes 前，请确认 git status、当前分支及目标远端仓库。

议题（Issue）

glab issue list --assignee=@me -O json
glab issue view 456 --comments
glab issue create -t "Bug in login" -l bug -d "Steps to reproduce"
glab issue update 456 --label "bug,confirmed"
glab issue close 456

CI/CD

glab ci list -s failed -F json
glab ci status --live
glab pipeline ci view -b main
glab ci trace lint
glab ci run -b main --variables DEPLOY_ENV:staging
glab ci retry lint
glab ci cancel pipeline 123

参考资料

仅加载与当前任务匹配的最小参考文件：

• references/quick-reference.md：简明速查表
• references/auth.md：认证机制、仓库上下文、自托管主机配置，以及 401/403/404 错误处理
• references/merge-requests.md：MR 工作流、评论、合并策略，以及 MR 特有错误
• references/issues.md：议题创建、编辑、关联，以及议题特有错误
• references/ci.md：流水线与作业检查、重试、取消、变量设置，以及 CI 错误处理
• references/api.md：关于 glab api 的使用、分页机制、GraphQL 调用及自动化模式

仅当当前任务所需参数标志、示例或故障排查信息超出本文件所涵盖范围时，才加载对应参考文件。