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 review comments
glab mr note <mr-number> -m "Please update tests"

管理问题

# 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

自动化和脚本编写

使用 JSON 输出进行解析：

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

使用 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. 在合并请求说明中使用“Closes #123”将合并请求关联到问题
4. 推送前检查 CI 配置：glab ci lint
5. 命令失败时检查仓库上下文：git remote -v

常用命令速查

合并请求：

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

问题：

• 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 查找现有合并请求

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

备注

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