GitLab CLI (glab)
Official CLI for GitLab. Manage issues, merge requests, pipelines, and more from the terminal.
Source: Inspired by NikiforovAll/glab-skill on Smithery.
⚠️ Security Notice
The glab api command provides unrestricted GitLab API access with your token.
- - A compromised or overly-permissive token can delete projects, modify settings, expose secrets
- Recommendation: Use tokens with minimal scopes:
-
read_api - Read-only operations
-
api - Full access (only when write operations needed)
- - For automation, consider project-level tokens with limited scope
- Never use tokens with
sudo scope unless required
Prerequisites
Required binaries:
- -
glab - GitLab CLI - INLINECODE5 - JSON processor (for scripts and API parsing)
Required credentials:
- -
GITLAB_TOKEN - GitLab personal access token
Optional configuration:
- -
GITLAB_HOST - Self-hosted GitLab instance (default: gitlab.com)
CODEBLOCK0
Quick Reference
Merge Requests:
CODEBLOCK1
Issues:
CODEBLOCK2
CI/CD:
CODEBLOCK3
Working Outside Repo:
CODEBLOCK4
Advanced API Access:
See references/api-advanced.md for glab api usage. This command enables arbitrary GitLab API calls and should be used with appropriately-scoped tokens.
Core Workflows
Create and Merge MR
CODEBLOCK5
Review MR
CODEBLOCK6
Monitor Pipeline
CODEBLOCK7
Self-Hosted GitLab
CODEBLOCK8
Scripts
| Script | Description |
|---|
| INLINECODE9 | Wait for MR approval and successful pipeline |
| INLINECODE10 |
Monitor pipeline with exit codes for CI |
CODEBLOCK9
Script environment variables:
- -
TIMEOUT - Max wait time in seconds (default varies by script) - INLINECODE12 - Polling interval in seconds (default 5-10s)
Troubleshooting
| Error | Fix |
|---|
| INLINECODE13 | Install glab |
| INLINECODE14 |
Install jq |
|
401 Unauthorized | Set
GITLAB_TOKEN or run
glab auth login |
|
404 Project Not Found | Verify repo name and permissions |
|
not a git repository | Use
-R owner/repo flag |
|
source branch already has MR |
glab mr list to find existing |
For detailed troubleshooting, see references/troubleshooting.md.
Progressive Disclosure
- - references/api-advanced.md -
glab api usage with security considerations - references/commands-detailed.md - Full command reference with all flags
- references/troubleshooting.md - Detailed error scenarios and solutions
Load these when you need specific flag details or are debugging issues.
Best Practices
- 1. Always verify auth: INLINECODE24
- Use minimal-scope tokens for read operations
- Link MRs to issues: "Closes #123" in description
- Lint CI config before pushing: INLINECODE25
- Use
--output=json for scripting - Most commands have
--web to open in browser
GitLab CLI (glab)
GitLab 官方命令行工具。在终端中管理议题、合并请求、流水线等。
来源： 灵感来源于 Smithery 上的 NikiforovAll/glab-skill。
⚠️ 安全提示
glab api 命令可使用你的令牌进行无限制的 GitLab API 访问。
- - 被泄露或权限过大的令牌可能导致项目被删除、设置被修改、机密信息被暴露
- 建议： 使用最小权限范围的令牌：
- read_api - 只读操作
- api - 完全访问权限（仅在需要写入操作时使用）
- - 对于自动化任务，考虑使用范围受限的项目级令牌
- 除非必要，否则不要使用带有 sudo 范围的令牌
前置条件
必需的二进制文件：
- - glab - GitLab CLI
- jq - JSON 处理器（用于脚本和 API 解析）
必需的凭证：
- - GITLAB_TOKEN - GitLab 个人访问令牌
可选配置：
- - GITLAB_HOST - 自托管 GitLab 实例（默认：gitlab.com）
bash
验证安装
glab --version
jq --version
身份验证（交互式）
glab auth login
或通过环境变量
export GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
export GITLAB_HOST=gitlab.example.org # 用于自托管
验证身份
glab auth status
快速参考
合并请求：
bash
glab mr create --title 修复 --description 关闭 #123
glab mr list --reviewer=@me # 等待你审核的 MR
glab mr checkout 123 # 本地测试 MR
glab mr approve 123 && glab mr merge 123
议题：
bash
glab issue create --title Bug --label=bug
glab issue list --assignee=@me
glab issue close 456
CI/CD：
bash
glab ci status # 当前流水线状态
glab pipeline ci view # 实时查看流水线
glab ci lint # 验证 .gitlab-ci.yml
glab ci retry # 重试失败的流水线
在仓库外操作：
bash
glab mr list -R owner/repo # 指定仓库
高级 API 访问：
有关 glab api 的使用，请参见 references/api-advanced.md。此命令可进行任意 GitLab API 调用，应使用适当权限范围的令牌。
核心工作流程
创建并合并 MR
bash
1. 推送分支
git push -u origin feature-branch
2. 创建 MR
glab mr create --title 添加功能 --description 实现 X --reviewer=alice,bob --label=enhancement
3. 审批通过后，合并
glab mr approve 123
glab mr merge 123 --remove-source-branch
审核 MR
bash
列出待审核的 MR
glab mr list --reviewer=@me
检出并测试
glab mr checkout 123
审批或评论
glab mr approve 123
glab mr note 123 -m 看起来不错，只有一个建议...
监控流水线
bash
查看当前分支的流水线
glab pipeline ci view
查看特定流水线
glab ci view 456
查看失败的任务日志
glab ci trace
重试
glab ci retry
自托管 GitLab
bash
设置默认主机
export GITLAB_HOST=gitlab.example.org
或按命令指定
glab mr list -R gitlab.example.org/owner/repo
脚本
| 脚本 | 描述 |
|---|
| glab-mr-await.sh | 等待 MR 审批和流水线成功 |
| glab-pipeline-watch.sh |
监控流水线，返回退出码供 CI 使用 |
bash
等待 MR 被审批并合并
./scripts/glab-mr-await.sh 123 --timeout 600
监控流水线，成功退出 0，失败退出 1
./scripts/glab-pipeline-watch.sh --timeout 300
脚本环境变量：
- - TIMEOUT - 最大等待时间（秒）（默认值因脚本而异）
- INTERVAL - 轮询间隔（秒）（默认 5-10 秒）
故障排除
| 错误 | 解决方法 |
|---|
| command not found: glab | 安装 glab |
| command not found: jq |
安装 jq |
| 401 Unauthorized | 设置 GITLAB_TOKEN 或运行 glab auth login |
| 404 Project Not Found | 验证仓库名称和权限 |
| not a git repository | 使用 -R owner/repo 标志 |
| source branch already has MR | 运行 glab mr list 查找现有 MR |
有关详细的故障排除，请参见 references/troubleshooting.md。
渐进式文档
- - references/api-advanced.md - glab api 的使用及安全注意事项
- references/commands-detailed.md - 包含所有标志的完整命令参考
- references/troubleshooting.md - 详细的错误场景和解决方案
当需要特定标志详情或调试问题时，请加载这些文档。
最佳实践
- 1. 始终验证身份：glab auth status
- 对只读操作使用最小权限范围的令牌
- 将 MR 链接到议题：在描述中使用 Closes #123
- 推送前检查 CI 配置：glab ci lint
- 编写脚本时使用 --output=json
- 大多数命令支持 --web 在浏览器中打开
