glab

GitLab CLI（glab）技能

介绍如何使用官方 GitLab CLI glab，在终端中执行 GitLab 操作。

何时使用此技能

在用户需要以下操作时调用：

• 创建、审核或管理合并请求
• 处理 GitLab 问题
• 监控或触发 CI/CD 流水线
• 克隆或管理仓库
• 从命令行执行任何 GitLab 操作

前置条件

执行命令前，确认已安装 glab：

glab --version

如果未安装，请告知用户，并提供适用于其平台的安装指南。

身份验证快速入门

大多数 glab 操作都需要身份验证：

# Interactive authentication
glab auth login

# Check authentication status
glab auth status

# For self-hosted GitLab
glab auth login --hostname gitlab.example.org

# Using environment variables
export GITLAB_TOKEN=your-token
export GITLAB_HOST=gitlab.example.org  # for self-hosted

核心工作流

创建合并请求

# 1. Ensure branch is pushed
git push -u origin feature-branch

# 2. Create MR
glab mr create --title "Add feature" --description "Implements X"

# With reviewers and labels
glab mr create --title "Fix bug" --reviewer=alice,bob --label="bug,urgent"

审核合并请求

# 1. List MRs awaiting your review
glab mr list --reviewer=@me

# 2. Checkout MR locally to test
glab mr checkout <mr-number>

# 3. After testing, approve
glab mr approve <mr-number>

# 4. Add a general comment
glab mr note <mr-number> -m "Please update tests"

发布行内 DiffNote 评论

要将评论锚定到差异中的特定行（即 DiffNote），必须使用带有 Content-Type: application/json 标头的 JSON 正文。使用 -F 表单字段会创建未锚定的 DiscussionNote。

# Get SHA values from the MR
glab mr view <id> --output=json | grep -oP '"(base_sha|head_sha|start_sha)":\s*"\K[0-9a-f]{40}'

# Post a DiffNote on a new line
glab api --method POST "projects/:id/merge_requests/:iid/discussions" \
  -H "Content-Type: application/json" \
  --input - <<'JSONEOF'
{
  "body": "Your review comment here",
  "position": {
    "base_sha": "<base_sha>",
    "start_sha": "<start_sha>",
    "head_sha": "<head_sha>",
    "position_type": "text",
    "new_path": "path/to/file.js",
    "new_line": 42
  }
}
JSONEOF

DiffNote 关键规则：

• 始终使用带 heredoc 的 --input - 和 -H "Content-Type: application/json"。切勿对 position 对象使用 -F，否则会静默创建 DiscussionNote。
• 行号是根据差异块标题（@@ -old,count +new,count @@）计算的新文件行号，而非差异输出中的行号。从差异块起始处开始，仅统计上下文行和 + 行。
• 在 MR 源分支上验证发现的问题（先运行 git fetch origin <branch>，再运行 git grep），而非在当前工作分支上验证。
• 更新现有备注：glab api --method PUT "projects/:id/merge_requests/:iid/notes/:note_id" -H "Content-Type: application/json" --input - <<< '{"body":"updated text"}'
• GitLab 没有类似 GitHub 的批量“提交审核”API。请逐条发布 DiffNote。
• 查找讨论或备注 ID：glab api "projects/:id/merge_requests/:iid/discussions" --paginate

管理问题

# Create issue with labels
glab issue create --title "Bug in login" --label=bug

# Link MR to issue
glab mr create --title "Fix login" --description "Closes #<issue-number>"

# List your assigned issues
glab issue list --assignee=@me

监控 CI/CD

# Watch pipeline in progress
glab pipeline ci view

# Check pipeline status
glab ci status

# View logs if failed
glab ci trace

# Retry failed pipeline
glab ci retry

# Lint CI config before pushing
glab ci lint

常见模式

在仓库上下文之外操作

不在 Git 仓库中时，请指定仓库：

glab mr list -R owner/repo
glab issue list -R owner/repo

自托管 GitLab

为所有命令设置主机名：

export GITLAB_HOST=gitlab.example.org
# or per-command
glab repo clone gitlab.example.org/owner/repo

列出未解决的 MR 评论

glab api "projects/:id/merge_requests/{mr}/discussions?per_page=100" | jq '[.[] | select(.notes[0].resolvable == true and .notes[0].resolved == false) | {id: .notes[0].id, body: .notes[0].body[0:100], path: .notes[0].position.new_path, line: .notes[0].position.new_line}]'

自动化与脚本编写

使用 JSON 输出进行解析：

glab mr list --output=json | jq '.[] | .title'

回复 MR 备注/讨论串

glab mr note 会创建独立评论。要在讨论串中回复，请使用 API：

# 1. Find the discussion_id containing the note
glab api "projects/:id/merge_requests/{mr}/discussions" | jq '.[] | select(.notes[].id == {note_id}) | .id'

# 2. Post reply to the discussion thread
glab api --method POST "projects/:id/merge_requests/{mr}/discussions/{discussion_id}/notes" --field body="Your reply"

示例：

# Get discussion_id for note 13698970
glab api "projects/:id/merge_requests/1013/discussions" | jq '.[] | select(.notes[].id == 13698970) | {id}'
# Returns: {"id": "5356c3552e72e7b4c49276eb4dacfe3efe5c2c5c"}

# Reply to that thread
glab api --method POST "projects/:id/merge_requests/1013/discussions/5356c3552e72e7b4c49276eb4dacfe3efe5c2c5c/notes" --field body="Thanks for the review!"

使用 API 命令

glab api 命令可直接访问 GitLab API：

# Basic API call
glab api projects/:id/merge_requests

# IMPORTANT: Pagination uses query parameters in URL, NOT flags
# ❌ WRONG: glab api --per-page=100 projects/:id/jobs
# ✓ CORRECT: glab api "projects/:id/jobs?per_page=100"

# Auto-fetch all pages
glab api --paginate "projects/:id/pipelines/123/jobs?per_page=100"

# POST with data
glab api --method POST projects/:id/issues --field title="Bug" --field description="Details"

最佳实践

1. 执行命令前验证身份验证状态：glab auth status
2. 使用 --help 了解命令选项：glab <command> --help
3. 在 MR 描述中使用“Closes #123”，将 MR 与问题关联
4. 推送前检查 CI 配置：glab ci lint
5. 命令失败时检查仓库上下文：git remote -v

常用命令速查

合并请求：

• glab mr list --assignee=@me - 分配给你的 MR
• glab mr list --reviewer=@me - 需要你审核的 MR
• glab mr create - 创建新 MR
• glab mr checkout <number> - 在本地测试 MR
• glab mr approve <number> - 批准 MR
• glab mr merge <number> - 合并已批准的 MR

问题：

• glab issue list - 列出所有问题
• glab issue create - 创建新问题
• glab issue close <number> - 关闭问题

CI/CD：

• glab pipeline ci view - 查看流水线
• glab ci status - 检查状态
• glab ci lint - 验证 .gitlab-ci.yml
• glab ci retry - 重试失败的流水线

仓库：

• glab repo clone owner/repo - 克隆仓库
• glab repo view - 查看仓库详情
• glab repo fork - 派生仓库

渐进式披露

如需详细的命令文档，请参阅：

• references/commands-detailed.md - 全面的命令参考，包含所有标志和选项
• references/quick-reference.md - 精简的命令速查表
• references/troubleshooting.md - 详细的错误场景和解决方案

在以下情况下加载这些参考文档：

• 用户需要了解特定标志或选项的详情
• 排查身份验证或连接问题
• 使用高级功能（API、计划、变量等）

常见问题快速修复

“command not found: glab” - 安装 glab 或检查 PATH

“401 Unauthorized” - 运行 glab auth login

“404 Project Not Found” - 检查仓库名称和访问权限

“not a git repository” - 切换到仓库目录，或使用 -R owner/repo 标志

“source branch already has a merge request” - 使用 glab mr list 查找现有 MR

如需详细的故障排查信息，请加载 references/troubleshooting.md。

说明

• glab 会根据 Git 远程仓库自动检测仓库上下文
• 大多数命令都支持 --web 标志，可在浏览器中打开
• 使用 --output=json 进行脚本编写和自动化
• 可同时对多个 GitLab 账户进行身份验证
• 命令会遵循 Git 配置和当前仓库上下文