glab-issue

glab issue

创建、查看、更新和管理 GitLab 议题。

模板选择

对于 create --template，不带路径的名称（可选带 .md）会在仓库的 .gitlab/issue_templates/ 目录下解析。绝对路径或包含路径分隔符的路径会直接读取；相对路径以当前目录为基准，并支持 ~/。对于当前目录中的文件，请使用 ./template.md，而不要使用不带路径的模板名称。发布前请先阅读并批准文件内容；--description-file 不能与 --template 同时使用。

指派、日期和内部备注

issue list --assignee @none 会筛选未指派的议题；--assignee @any 会筛选已指派的议题，而 @me 会筛选你的议题。日期筛选项为 --created-after、--created-before、--updated-after 和 --updated-before，时间戳须包含时区，并符合 RFC 3339 格式。群组列表会保留 --confidential 和 --iteration 筛选条件。

glab issue list --assignee @none --updated-after 2026-10-01T00:00:00Z
glab issue note 123 --internal --message "Investigation details for project members"

--internal 会请求创建仅项目成员可见的内部备注；发布前请确认目标和受众，且切勿包含凭据。issue view 在有数据时会显示易读的已用时长和预计时长；自动化场景请优先使用 JSON。

快速开始

# Create an issue
glab issue create --title "Fix login bug" --label bug

# Create or update with a multi-line description from a file
glab issue create --title "Fix login bug" --description-file description.md
glab issue update 123 --description-file description.md

# Upload a screenshot and append its Markdown reference
glab issue create --title "Fix login bug" --description "See below." --attach ./repro.png
glab issue update 123 --attach ./after.png

# List open issues
glab issue list --state opened

# Stable machine-readable output
glab issue list --output json

# View issue details
glab issue view 123

# View or comment on an issue/work item from a GitLab URL
glab issue view https://gitlab.com/group/project/-/work_items/123

glab issue note https://gitlab.com/group/project/-/issues/123 -m "Working on this now"

# Add comment
glab issue note 123 -m "Working on this now"

# Close issue
glab issue close 123

常见工作流

议题和工作项 URL 输入

在 glab issue 子命令将议题参数解析为议题时，参数解析也接受 GitLab 工作项 URL，而不仅限于议题 URL。这是针对 view、note、update、close 等议题类操作的 URL 兼容支持；若需要专用的工作项字段或工作项特有的生命周期行为，请使用 glab work-items。

glab issue view https://gitlab.com/group/project/-/work_items/123
glab issue note https://gitlab.com/group/project/-/work_items/123 -m "Follow-up note"
glab issue update https://gitlab.com/group/project/-/work_items/123 --label needs-triage

Bug 报告工作流

1. 创建 Bug 议题：

   glab issue create \
     --title "Login fails with 500 error" \
     --label bug \
     --label priority::high \
     --assignee @dev-lead
   

   如果项目在仓库中保存了可复用的议题模板，请使用 --template 从模板文件开始，而不是粘贴重复的固定内容：

   glab issue create \
     --title "Login fails with 500 error" \
     --template .gitlab/issue_templates/bug.md \
     --label bug
   

   对于一次性的多行描述，请使用 --description-file <path>，或使用 --description-file - 从标准输入读取。它不能与 --description 同时使用；创建时也不能与 --template 同时使用。内容恰好为 - 的文件会被拒绝，因为 --description - 表示“打开编辑器”。

   使用实验性的 --attach <path> 可重复上传一个或多个本地文件，并将 GitLab 提供的 Markdown 引用追加到描述中。--attach - 会从标准输入读取一个附件；请勿将其与 --description-file - 同时使用，因为两者都会读取标准输入。创建时，只需提供 --title 和附件即可进行非交互操作。更新时，除非通过 --description 或 --description-file 提供替换正文，否则附件会追加到现有描述中。

2. 添加复现步骤：

   glab issue note 456 -m "Steps to reproduce:
   1. Navigate to /login
   2. Enter valid credentials
   3. Click submit
   Expected: Dashboard loads
   Actual: 500 error"
   
   # A file can accompany a message or be the entire comment
   glab issue note 456 -m "Screenshot from production" --attach ./repro.png
   

   重复使用 --attach 可按参数顺序保留多个上传文件。仅包含附件的备注会跳过编辑器；通过标准输入传入单个文件时，请使用 --attach -。

议题分类

文本列表的标题使用 API 返回的项目和群组议题总数，并与当前页的行数分开显示。当 API 未提供总数，或列出客户端筛选的 Epic 议题时，glab 不会根据当前页的行数推算总数。JSON 输出仍包含已获取的议题行；修正后的标题不会额外获取其他页面。

glab issue list 会在发出请求前验证两个输出选择器：--output 仅接受 text 或 json，而 --output-format 仅接受 details、ids 或 urls。这两个选择器不能同时使用。遇到立即返回的“必须是以下值之一”错误时，应将其视为无效的本地输入，而非 GitLab API 故障。

1. 列出未分类的议题：

   glab issue list --label needs-triage --state opened
   

2. 更新标签和指派对象：

   glab issue update 789 \
     --label backend,priority::medium \
     --assignee @backend-team \
     --milestone "Sprint 23"
   
   glab issue update 789 --description-file triage-summary.md
   

3. 移除分类标签：

   glab issue update 789 --unlabel needs-triage
   

批量添加标签：

若要一次性为多个议题添加标签，请使用此技能在 scripts/ 下附带的脚本（以下路径均相对于技能自身目录）：

scripts/batch-label-issues.sh "priority::high" 100 101 102
scripts/batch-label-issues.sh bug 200 201 202 203

时间跟踪

# Set an estimate and add spent time
glab issue update 42 --estimate 2d --spend 1h30m

# Reset both values after confirming the intended issue
glab issue update 42 --remove-estimate --remove-time-spent

时长采用 GitLab 的时间跟踪格式，例如 1mo 2w 3d 4h 5m。--estimate 用于设置预估时长；--spend 用于在现有已用时长的基础上增加时长。每个重置标志都与对应的设置／添加标志冲突。这些是更新标志；创建议题时使用 --time-estimate 和 --time-spent。

仅更新时间时，会跳过常规议题更新请求。如果同时进行其他编辑，这些编辑会先执行，然后再单独发送时间跟踪请求。后续操作失败时，之前的更改可能已经生效。重试前请先检查议题，尤其是在再次使用增量式 --spend 之前。

冲刺规划

查看当前冲刺议题：

glab issue list --milestone "Sprint 23" --assignee @me

添加到冲刺：

glab issue update 456 --milestone "Sprint 23"

看板视图：

glab issue board view

# Retrieve every project/group board issue instead of only the first API page
glab issue board view --paginate

如果看板可能超过一页 API 返回结果，请使用 --paginate 完整查看看板议题。否则，交互式看板会使用 GitLab 返回的第一页结果。此选项适用于项目和群组看板的议题检索，也可与 --assignee、--labels 或 --milestone 筛选条件搭配使用。

将议题与工作关联

为议题创建 MR：

glab mr for 456  # Creates MR that closes issue #456

自动化工作流（创建分支 + 草稿 MR）：

scripts/create-mr-from-issue.sh 456 --create-mr

此操作会自动：根据议题标题创建分支 → 空提交 → 推送 → 创建草稿 MR。

通过提交／MR 关闭：

git commit -m "Fix login bug

Closes #456"

相关技能

从议题创建 MR：

• 查看 glab-mr，了解合并请求操作
• 使用 glab mr for <issue-id> 创建可关闭议题的 MR
• 脚本：scripts/create-mr-from-issue.sh 可自动创建分支和草稿 MR

标签管理：

• 查看 glab-label，了解如何创建和管理标签
• 脚本：scripts/batch-label-issues.sh 用于批量添加标签

项目规划：

• 查看 glab-milestone，了解发布规划
• 查看 glab-iteration，了解冲刺／迭代管理

命令参考

完整的命令文档和所有标志，请参阅 references/commands.md。

可用命令：

• create - 创建新议题
• list - 使用筛选条件列出议题
• view - 显示议题详情
• note - 为议题添加评论
• update - 更新标题、标签、受派人、里程碑和时间跟踪
• close - 关闭议题
• reopen - 重新打开已关闭的议题
• delete - 删除议题
• subscribe / unsubscribe - 管理通知
• board - 使用议题看板