glab

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GitLab CLI (glab) Skill

GitLab CLI（glab）技能指南

Provides guidance for using

glab

, the official GitLab CLI, to perform GitLab operations from the terminal.

本指南提供如何使用官方GitLab CLI工具

glab

从终端执行GitLab操作的相关指导。

When to Use This Skill

何时使用本技能

Invoke when the user needs to:

Create, review, or manage merge requests
Work with GitLab issues
Monitor or trigger CI/CD pipelines
Clone or manage repositories
Perform any GitLab operation from the command line

当用户需要以下操作时，可调用本技能：

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

Prerequisites

前置条件

Verify glab installation before executing commands:

bash

glab --version

If not installed, inform the user and provide platform-specific installation guidance.

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

bash

glab --version

若未安装，请告知用户并提供对应平台的安装指引。

Authentication Quick Start

认证快速入门

Most glab operations require authentication:

bash

undefined

大多数glab操作需要认证：

bash

undefined

Interactive authentication

交互式认证

glab auth login

Check authentication status

检查认证状态

glab auth status

For self-hosted GitLab

针对自建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

undefined

export GITLAB_TOKEN=your-token export GITLAB_HOST=gitlab.example.org # 适用于自建实例

undefined

Core Workflows

核心工作流

Creating a Merge Request

创建合并请求

bash

undefined

bash

undefined

1. Ensure branch is pushed

1. 确保分支已推送

git push -u origin feature-branch

2. Create MR

2. 创建合并请求

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"

undefined

glab mr create --title "Fix bug" --reviewer=alice,bob --label="bug,urgent"

undefined

Reviewing Merge Requests

评审合并请求

bash

undefined

bash

undefined

1. List MRs awaiting your review

1. 列出等待你评审的合并请求

glab mr list --reviewer=@me

2. Checkout MR locally to test

2. 拉取合并请求到本地测试

glab mr checkout <mr-number>

3. After testing, approve

3. 测试完成后批准合并请求

glab mr approve <mr-number>

4. Add review comments

4. 添加评审评论

glab mr note <mr-number> -m "Please update tests"

undefined

glab mr note <mr-number> -m "Please update tests"

undefined

Managing Issues

管理议题

bash

undefined

bash

undefined

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

undefined

glab issue list --assignee=@me

undefined

Monitoring CI/CD

监控CI/CD流水线

bash

undefined

bash

undefined

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

推送前校验CI配置

glab ci lint

undefined

glab ci lint

undefined

Common Patterns

常见使用场景

Working Outside Repository Context

在仓库上下文外操作

When not in a Git repository, specify the repository:

bash

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

当不在Git仓库目录下时，需指定仓库：

bash

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

Self-Hosted GitLab

自建GitLab实例

Set hostname for all commands:

bash

export GITLAB_HOST=gitlab.example.org

为所有命令设置主机名：

bash

export GITLAB_HOST=gitlab.example.org

or per-command

或针对单个命令设置

glab repo clone gitlab.example.org/owner/repo

undefined

glab repo clone gitlab.example.org/owner/repo

undefined

Listing Unresolved MR Comments

列出未解决的合并请求评论

bash

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}]'

bash

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}]'

Automation and Scripting

自动化与脚本编写

Use JSON output for parsing:

bash

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

使用JSON输出以便解析：

bash

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

Replying to MR Notes/Threads

回复合并请求的评论/线程

glab mr note

creates standalone comments. To reply within a discussion thread, use the API:

bash

undefined

glab mr note

用于创建独立评论。要在讨论线程内回复，请使用API：

bash

undefined

1. Find the discussion_id containing the note

1. 找到包含目标评论的discussion_id

glab api "projects/:id/merge_requests/{mr}/discussions" | jq '.[] | select(.notes[].id == {note_id}) | .id'

2. Post reply to the discussion thread

2. 向讨论线程推送回复

glab api --method POST "projects/:id/merge_requests/{mr}/discussions/{discussion_id}/notes" --field body="Your reply"


Example:
```bash

glab api --method POST "projects/:id/merge_requests/{mr}/discussions/{discussion_id}/notes" --field body="Your reply"


示例：
```bash

Get discussion_id for note 13698970

获取评论ID为13698970对应的discussion_id

glab api "projects/:id/merge_requests/1013/discussions" | jq '.[] | select(.notes[].id == 13698970) | {id}'

Returns: {"id": "5356c3552e72e7b4c49276eb4dacfe3efe5c2c5c"}

返回结果：{"id": "5356c3552e72e7b4c49276eb4dacfe3efe5c2c5c"}

Reply to that thread

回复该线程

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

undefined

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

undefined

Using the API Command

使用API命令

The

glab api

command provides direct GitLab API access:

bash

undefined

glab api

命令可直接调用GitLab API：

bash

undefined

Basic API call

基础API调用

glab api projects/:id/merge_requests

IMPORTANT: Pagination uses query parameters in URL, NOT flags

重要提示：分页需在URL中使用查询参数，而非标志位

❌ WRONG: glab api --per-page=100 projects/:id/jobs

❌ 错误用法：glab api --per-page=100 projects/:id/jobs

✓ CORRECT: glab api "projects/:id/jobs?per_page=100"

✓ 正确用法：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

发送POST请求并携带数据

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

undefined

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

undefined

Best Practices

最佳实践

Verify authentication before executing commands:
```
glab auth status
```
Use
--help
to explore command options:
```
glab <command> --help
```
Link MRs to issues using "Closes #123" in MR description
Lint CI config before pushing:
```
glab ci lint
```
Check repository context when commands fail:
```
git remote -v
```

执行命令前验证认证状态：
```
glab auth status
```
使用
--help
探索命令选项：
```
glab <command> --help
```
在合并请求描述中使用"Closes #123"关联议题
推送前校验CI配置：
```
glab ci lint
```
命令失败时检查仓库上下文：
```
git remote -v
```

Common Commands Quick Reference

常用命令速查

Merge Requests:

```
glab mr list --assignee=@me
```
- Your assigned MRs
```
glab mr list --reviewer=@me
```
- MRs for you to review
```
glab mr create
```
- Create new MR
```
glab mr checkout <number>
```
- Test MR locally
```
glab mr approve <number>
```
- Approve MR
```
glab mr merge <number>
```
- Merge approved MR

Issues:

```
glab issue list
```
- List all issues
```
glab issue create
```
- Create new issue
```
glab issue close <number>
```
- Close issue

CI/CD:

```
glab pipeline ci view
```
- Watch pipeline
```
glab ci status
```
- Check status
```
glab ci lint
```
- Validate .gitlab-ci.yml
```
glab ci retry
```
- Retry failed pipeline

Repository:

```
glab repo clone owner/repo
```
- Clone repository
```
glab repo view
```
- View repo details
```
glab repo fork
```
- Fork repository

合并请求：

```
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
```
- Fork仓库

Progressive Disclosure

进阶参考

For detailed command documentation, refer to:

references/commands-detailed.md - Comprehensive command reference with all flags and options
references/quick-reference.md - Condensed command cheat sheet
references/troubleshooting.md - Detailed error scenarios and solutions

Load these references when:

User needs specific flag or option details
Troubleshooting authentication or connection issues
Working with advanced features (API, schedules, variables, etc.)

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

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

在以下场景中可加载这些参考文档：

用户需要特定标志位或选项的详细信息
排查认证或连接问题
使用高级功能（API、调度、变量等）

Common Issues Quick Fixes

常见问题快速修复

"command not found: glab" - Install glab or verify PATH

"401 Unauthorized" - Run

glab auth login

"404 Project Not Found" - Verify repository name and access permissions

"not a git repository" - Navigate to repo or use

-R owner/repo

flag

"source branch already has a merge request" - Use

glab mr list

to find existing MR

For detailed troubleshooting, load references/troubleshooting.md.

"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。

Notes

注意事项

glab auto-detects repository context from Git remote
Most commands have
```
--web
```
flag to open in browser
Use
```
--output=json
```
for scripting and automation
Multiple GitLab accounts can be authenticated simultaneously
Commands respect Git configuration and current repository context

glab会自动从Git远程仓库检测上下文
大多数命令支持
```
--web
```
标志位，可在浏览器中打开对应页面
使用
```
--output=json
```
格式输出以便自动化脚本解析
可同时认证多个GitLab账号
命令会遵循Git配置及当前仓库上下文