GitLab CLI

GLab

GLab 是一款开源的 GitLab 命令行工具。它将 GitLab 带到你的终端中，就在你使用 git 和代码工作的地方，无需在窗口和浏览器标签页之间切换。glab 不仅能处理问题和合并请求，还能做更多事情：

• 直接从命令行查看、管理和重试 CI/CD 流水线。
• 创建变更日志。
• 创建和管理发布。
• 向 GitLab Duo Chat (Classic) 提出有关 Git 的问题。
• 管理 Kubernetes 的 GitLab Agent。

glab 适用于托管在 GitLab.com、GitLab Dedicated 和 GitLab Self-Managed 上的仓库。它支持多个已通过身份验证的 GitLab 实例，并会根据当前 Git 工作目录中的远程仓库，自动检测已通过身份验证的主机名。

目录

• 要求
• 使用方法
  • 命令
  • 面向命令行的 GitLab Duo
• 演示
• 文档
• 安装
  • Homebrew
  • 其他安装方式
  • 从源代码构建
    • 从源代码构建的先决条件
• 身份验证
• 配置
• 环境变量
  • 调试
• 故障排除
• 问题
• 安全
• 参与贡献
  • 版本控制
  • 版本变更分类
  • 兼容性
• 灵感来源

要求

glab 官方支持 GitLab 16.0 及更高版本。某些命令可能需要更新的版本。许多命令可能在 GitLab 15.x 及更早版本中正常运行，但这些版本不受支持。

使用方法

开始使用 glab：

1. 按照适用于你操作系统的安装说明进行安装。
2. 在你的 GitLab 实例中进行身份验证。
3. 可选。根据需要进一步配置 glab：
   • 1Password 用户可以将其配置为对 glab 进行身份验证。
   • 设置所需的全局、项目级或主机级配置。
   • 设置所需的环境变量。

现在可以开始使用了！

命令

运行 glab --help，即可在终端中查看核心命令列表。

• glab alias：创建、列出和删除别名。
• glab api：向 GitLab API 发起经过身份验证的请求。
• glab artifact-registry：使用 GitLab Artifact Registry 进行身份验证。（实验性）
• glab attestation：管理软件证明。（实验性）
• glab auth：管理 glab 的身份验证。
• glab changelog：根据项目的提交历史生成变更日志。
• glab check-update：检查 glab 的最新版本。
• glab ci：使用 GitLab CI/CD 流水线和作业。
• glab cluster：管理用于 Kubernetes 的 GitLab Agent 及其集群。
• glab completion：生成 Shell 自动补全脚本。
• glab config：管理 glab 设置。
• glab container-registry：使用 GitLab 容器注册表。
• glab dependency-firewall：为本地包管理器配置和监控 GitLab Dependency Firewall。（实验性）
• glab deploy-key：管理部署密钥。
• glab deploy-token：管理部署令牌。
• glab duo：使用 GitLab Duo。
• glab govern：管理 AI 治理。（实验性）
• glab gpg-key：管理注册到 GitLab 账户的 GPG 密钥。
• glab incident：处理 GitLab 事件。
• glab issue：处理 GitLab 议题。
• glab iteration：获取迭代信息。
• glab job：处理 GitLab CI/CD 作业。
• glab label：管理项目和群组标签。
• glab milestone：管理群组或项目里程碑。
• glab mr：创建、查看和管理合并请求。
• glab opentofu：使用 OpenTofu 或 Terraform 集成。
• glab orbit：查询 GitLab Orbit 上下文图。（实验性）
• glab packages：管理 GitLab 包注册表中的软件包。
• glab release：管理 GitLab 发布。
• glab repo：使用 GitLab 仓库和项目。
• glab runner：管理 GitLab CI/CD Runner。
• glab runner-controller：管理 Runner 控制器。（实验性）
• glab schedule：使用 GitLab CI/CD 计划。
• glab search：搜索 GitLab 项目中的代码和资源。（Beta）
• glab securefile：管理项目的安全文件。
• glab security：管理项目的 GitLab 安全扫描配置文件。（实验性）
• glab skills：管理 glab Agent 技能。（实验性）
• glab snippet：创建代码片段。
• glab ssh-key：管理注册到 GitLab 账户的 SSH 密钥。
• glab stack：创建、管理和处理堆叠式差异。（实验性）
• glab todo：管理待办事项列表。
• glab token：管理个人、项目或群组令牌。
• glab user：与 GitLab 用户账户交互。
• glab variable：管理 GitLab 项目或群组的变量。
• glab version：显示 glab 的版本信息。
• glab whatsnew：显示 glab 新版本的发行说明。
• glab work-items：管理工作项。（实验性）

命令遵循以下模式：

glab <command> <subcommand> [flags]

许多核心命令还提供子命令。以下是一些示例：

• 列出分配给你的合并请求：glab mr list --assignee=@me
• 列出请求你审查的合并请求：glab mr list --reviewer=@me
• 批准合并请求：glab mr approve 235
• 创建议题，并添加里程碑、标题和标签：glab issue create -m release-2.0.0 -t "My title here" --label important

用于命令行的 GitLab Duo

GitLab CLI 还支持在终端中直接使用 GitLab Duo Agent Platform。

使用 glab duo cli 向 GitLab Duo 询问有关代码库的问题，并让它自主代你执行操作。

如需了解更多信息，请参阅 GitLab Duo CLI。

演示

文档

请阅读文档了解使用说明，或查看 glab help。

安装

在发布页面下载适用于你操作系统的二进制文件。 其他安装方式取决于你的操作系统。

Homebrew

Homebrew 是适用于 macOS、Linux 和 Windows（通过 Windows Subsystem for Linux）的官方支持包管理器

• Homebrew
  • 安装：brew install glab
  • 更新：brew upgrade glab

其他安装方式

其他 GitLab CLI 安装方式可能不受官方支持，或由社区维护，也可使用。

从源代码构建

如果发布页面上没有适用于你操作系统的受支持二进制文件，你可以从源代码构建：

从源代码构建的先决条件

• make
• main/go.mod 中指定的 Go 版本

从源代码构建：

1. 运行 go version，确认你拥有所需的最低 Go 版本。 如果尚未安装 Go，请参阅下载和安装。
2. 克隆仓库：git clone https://gitlab.com/gitlab-org/cli.git
3. 构建二进制文件：make build
4. 将 glab 安装到 $GOPATH/bin：make install
5. 可选。如果 $GOPATH/bin 或 $GOBIN 不在你的 $PATH 中， 请运行 export PATH=$PWD/bin:$PATH。
6. 确认安装：glab version

身份验证

如需了解如何使用 OAuth、个人访问令牌或 CI 作业令牌对 glab 进行身份验证，请参阅 使用 GitLab 进行身份验证。

配置

如需了解配置级别、配置搜索顺序和平台专属文件位置，请参阅配置 CLI。

如需了解如何连接到 GitLab Self-Managed 或 GitLab Dedicated 实例，以及 mTLS 和自签名证书，请参阅 连接到你的 GitLab 实例。

如需了解代理身份验证，包括自定义 HTTP 标头和 Google Identity-Aware Proxy，请参阅通过代理连接。

环境变量

glab 会从环境变量和配置文件中读取配置。每个配置键都有对应的变量，且变量的优先级高于已存储的值。在组织内集中设置这些变量，是让所有人使用相同配置的好方法。

完整参考请参阅 环境变量。 如需了解 glab 如何选择要使用的令牌，请参阅 令牌优先级。

调试

将 GLAB_DEBUG 环境变量设为 true 时，glab 会输出更多日志信息，包括：

• 底层 Git 命令。
• 展开的别名。
• DNS 错误详情。

故障排查

有关常见身份验证问题的帮助，请参阅 GitLab CLI 文档中的 故障排查。

问题

如果遇到问题，请在问题跟踪器中报告。

安全

要报告 glab 中的安全漏洞，请按照安全政策中的流程操作。请勿公开提交问题。

要了解项目如何处理依赖项更新和容器扫描器 CVE 报告，请参阅 CONTRIBUTING.md 中的依赖项管理 和报告漏洞。

贡献

想要贡献？太棒了！我们提供了贡献指南和行为准则来为你提供指引。

更新命令帮助文本或文档时，请遵循 GitLab CLI 文档风格指南。

版本管理

本项目遵循 SemVer 规范。

版本变更分类

• 如果删除命令、更改命令行为或添加新的必需标志，发布时必须使用新的 MAJOR 版本号。
• 如果添加新命令或可选标志，发布时必须使用新的 MINOR 版本号。
• 如果修复错误，发布时必须使用新的 PATCH 版本号。

兼容性

我们会尽力只在发布新的 MAJOR 版本时引入不兼容变更。 遗憾的是，有些情况下无法做到这一点，我们可能会在 MINOR 或 PATCH 版本中引入 不兼容变更。以下是一些可能这样做的情况：

• 如果发现安全问题，且解决方案需要引入不兼容变更， 我们可能会引入此类变更来解决问题并保护用户。
• 如果某项功能未按预期工作，且错误修复需要引入不兼容变更， 我们可能会引入此修复，以确保功能按预期工作。
• 如果功能规范含糊不清，导致其行为令人困惑。在这种情况下，我们可能会完善规范， 消除歧义，并引入与完善后的规范一致的不兼容变更。相关示例请参阅 合并请求 1382。
• 实验性功能不保证稳定，可能会被修改或移除，且无需引入不兼容变更。

不兼容变更是最后手段，我们会尽力只在绝对必要时才引入。

灵感来源

2022 年，GitLab CLI 从 Clement Sam 手中接手，成为 GitLab 官方 CLI。多年来，该项目受到 GitHub CLI 和 Zaq? Wiedmann 的 lab 的启发。

Lab 为许多 GitLab CI/CD 命令奠定了基础，包括 ci view 和 ci trace。