gitlab

所有操作均使用 glab CLI。用户的 OAuth 访问令牌已导出为 $GITLAB_TOKEN；glab 会自动读取（为兼容工具，该令牌也可通过 GITLAB_ACCESS_TOKEN 和 OAUTH_TOKEN 使用）。默认主机为 gitlab.com；对于可自托管实例，请设置 GITLAB_HOST，或在每条命令中传入 --hostname <host>。

glab --help 和 glab <subcommand> --help 始终是最新的。

调用 glab 的两种方式——优先使用子命令

方式 A：一等子命令——从这里开始

glab issue、glab mr、glab repo、glab ci、glab job、glab pipeline、 glab release、glab snippet、glab variable、glab label、 glab milestone、glab schedule。这些命令默认输出格式化文本， 并可通过 --output json 输出 JSON。

方式 B：通过 glab api 调用原始 REST / GraphQL

REST 使用 glab api <path>，GraphQL 使用 glab api graphql -f query='…'。 常用标志：

• -X POST|PATCH|PUT|DELETE — 覆盖请求方法（默认为 GET；设置 --field / --raw-field 时则变为 POST）。
• -f key=value — 自动识别类型（字面值 true / false / null / 整数会转换为 JSON 类型；以 @filename 开头的值会从文件读取）。
• -F key=value — 与 -f 相同，但始终将值视为字符串。
• --paginate — 自动遍历 Link: rel="next"。
• --hostname <host> — 将目标设为默认 GitLab 主机之外的其他主机。
• 路径占位符：在 git 工作区内运行时，:fullpath / :branch / :user 会自动从仓库填充。在通用 shell 中运行时，需手动对路径编码（参见示例）。

示例

列出项目中未关闭的问题

glab issue list --repo OWNER/PROJECT --opened --output json
glab issue list --repo OWNER/PROJECT --assignee=@me --output json

查看带评论的问题

glab issue view 42 --repo OWNER/PROJECT --comments
glab issue view 42 --repo OWNER/PROJECT --output json

创建 / 评论 / 关闭问题

glab issue create --repo OWNER/PROJECT --title "Bug: foo" --description "Repro steps…" --label bug
glab issue note 42 --repo OWNER/PROJECT --message "Acknowledged."
glab issue close 42 --repo OWNER/PROJECT

列出分配给我 / 由我创建的合并请求

glab mr list --repo OWNER/PROJECT --assignee=@me --opened --output json
glab mr list --repo OWNER/PROJECT --author=@me --opened

查看包含差异和 CI 流水线的合并请求

glab mr view 99 --repo OWNER/PROJECT
glab mr diff 99 --repo OWNER/PROJECT
glab ci view --repo OWNER/PROJECT --branch <BRANCH>

批准 / 合并 / 在合并请求中留言

glab mr approve 99 --repo OWNER/PROJECT
glab mr note 99 --repo OWNER/PROJECT --message "Looks good — ready when CI is green."
glab mr merge 99 --repo OWNER/PROJECT --squash --remove-source-branch

读取默认分支中的文件（原始字节）

# URL-encode the project path AND the file path because both contain '/'.
PROJECT=$(printf '%s' 'OWNER/PROJECT' | jq -sRr @uri)
FILE=$(printf '%s' 'src/main.go' | jq -sRr @uri)
glab api "projects/${PROJECT}/repository/files/${FILE}/raw?ref=main"

列出某个分支上的最新流水线

glab ci list --repo OWNER/PROJECT --status running,success,failed
glab ci view --repo OWNER/PROJECT --branch main
glab ci trace --repo OWNER/PROJECT <JOB_ID>     # stream a job log

搜索某个群组中的问题

glab api "groups/GROUP_PATH_OR_ID/issues?state=opened&search=keyword" \
  --paginate \
  | jq '.[] | {iid, title, project: .references.full, web_url}'

GraphQL 示例：项目元数据 + 未关闭的合并请求数量

glab api graphql -f query='
  query($path: ID!) {
    project(fullPath: $path) {
      name webUrl
      mergeRequests(state: opened) { count }
    }
  }' -f path=OWNER/PROJECT

说明

• --repo OWNER/PROJECT 接受 OWNER/PROJECT、GROUP/SUBGROUP/PROJECT、 完整 HTTPS URL 或 git URL。对于 --repo，项目路径会原样传递（不进行 URL 编码）；但在 glab api 路径中使用时，需通过 jq @uri 进行编码。
• 对于可自托管的 GitLab，用户必须已使用正确的 host 授权连接。 对于已知存在的项目，如果收到 404，通常意味着连接指向了 gitlab.com，而项目实际位于 其他位置——请向用户提示这一点。
• 许多 glab 命令都有 --output 标志，可接受 text（默认值） 或 json。glab issue list 和 glab mr list 另外支持 --output-format（details / ids / urls），这是仅适用于列表的独立格式化选项。传入完整标志 --output json，以避免短标志混淆（-O 与 -F）。