glab-workitems

glab work-items

创建、列出和删除 GitLab 工作项——GitLab 统一的工作跟踪模型，适用于任务、OKR、关键结果、史诗、事件、测试用例及相关规划对象。

分配迭代

创建或更新时，使用 --iteration 指定数字迭代 ID：

glab work-items create --type issue --title "Add feature" --iteration 123
glab work-items update 42 --iteration 123

省略此标志后，创建时迭代将保持未设置，更新时迭代则保持不变。写入前，请确认工作项的范围和目标迭代；不要用迭代标题代替 ID。

⚠️ 实验性功能

上游仍将 glab work-items 标记为 EXPERIMENTAL：

• 命令形式可能仍会变化
• 可用性可能因 GitLab 版本／功能标志而异
• 某些工作项类型仅适用于群组范围
• 日常稳定的问题工作流请使用 glab issue

参见：https://docs.gitlab.com/policy/development_stages_support/

快速开始

# List work items in the current project
glab work-items list

# Create a task in the current project
glab work-items create --type task --title "Follow up on flaky pipeline"

# Create or update with a multi-line description from a file
glab work-items create --type task --title "Follow up" --description-file description.md
glab work-items update 42 --description-file description.md

# Attach a project-scoped file reference
glab work-items create --type task --title "Follow up" --attach ./evidence.png
glab work-items update 42 --attach ./latest.png

# Create a group-scoped epic
glab work-items create --type epic --group my-group --title "Platform rewrite"

范围模型

默认情况下，glab work-items 使用仓库上下文，也可以显式指定其他范围：

• 当前仓库上下文 → 当前检出仓库中的项目工作项
• --repo owner/project → 其他项目
• --group my-group → 群组／子群组工作项

这一点很重要，因为某些工作项类型通常属于项目范围（task、issue、incident），而另一些通常属于群组范围（epic、objective、key_result）。

常见工作流

列出工作项

# First 20 open work items in current project
glab work-items list

# Filter by type
glab work-items list --type epic --group gitlab-org
glab work-items list --type issue --repo gitlab-org/cli

# Closed or all states
glab work-items list --state closed --group gitlab-org
glab work-items list --state all --group gitlab-org

# Increase page size (max 100)
glab work-items list --per-page 50 --group gitlab-org

# Cursor-based pagination
glab work-items list --after "eyJpZCI6OTk5OX0" --group gitlab-org

# JSON output for automation
glab work-items list --output json --group gitlab-org

创建工作项

使用 --type 显式声明工作项类型。

# Create a project work item
glab work-items create \
  --type task \
  --title "Audit runner costs" \
  --description "Summarize shared-runner usage before Friday"

# Create a confidential incident
glab work-items create \
  --type incident \
  --title "Investigate production latency spike" \
  --confidential

# Create a group-scoped epic
glab work-items create \
  --type epic \
  --group my-group \
  --title "Q3 platform migration"

# JSON output for scripts
glab work-items create --type issue --title "Backfill docs" --output json

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

实验性的 --attach <path> 标志会上传文件，并将返回的 Markdown 引用追加到描述中。多个文件可重复使用该标志；也可以使用 --attach - 从标准输入添加一个附件，但不要同时从标准输入读取描述。更新时，仅提供附件会保留当前描述并追加引用；显式提供描述则会先替换正文。上传操作限定于项目范围，因此 --attach 不能与 --group 一起使用。

上游支持的类型值包括： epic、incident、issue、key_result、objective、requirement、task、test_case 和 ticket。

删除工作项

# Delete by IID in the current project
glab work-items delete 42

# Delete a group work item
glab work-items delete 42 --group my-group

# Delete from another project and return JSON
glab work-items delete 42 --repo mygroup/myproject --output json

delete 会造成破坏性更改。运行前，请仔细确认 IID 属于目标项目或群组。

更新工作项

# Update body text in the current project
glab work-items update 42 --description-file description.md

# Update a group-scoped work item
glab work-items update 40 --group MYGROUP --description-file epic-update.md

工作项与问题

需求	优先使用
标准的 Bug／功能问题工作流	glab issue
任务、OKR、目标、关键结果、新一代史诗	glab work-items
稳定／非实验性的问题自动化	glab issue
群组范围的规划对象	glab work-items --group ...

当工作类型本身很重要时，使用 glab work-items。如果只需要标准的问题生命周期命令，并希望使用最成熟的 CLI 功能，则使用 glab issue。

故障排查

提示 work-items: command not found，或文档中显示 workitems：

• 当前上游命令系列是带连字符的 glab work-items。
• 不带连字符的 glab workitems 示例已过时。
• 排查本地命令是否可用时，请使用 glab version 检查版本。

在你的计算机上似乎无法创建／删除：

• 使用 glab work-items --help 确认本地命令是否可用；如果缺少 create／delete 子命令，请升级 glab。

类型筛选器未返回任何结果：

• 并非每个 GitLab 实例都会提供所有工作项类型。
• 请尝试为所查询的类型选择正确的范围（--group 或 --repo）。

删除了错误的对象：

• delete 会在所选项目／群组范围内按 IID 操作。
• 请使用显式的 --repo 或 --group 重新运行，以明确指定范围。

相关技能

• glab-issue — 标准问题工作流
• glab-milestone — 常与 OKR 和规划配合使用的里程碑
• glab-iteration — Sprint / 迭代规划
• glab-incident — 事件专用工作流

命令参考

有关受影响命令的完整帮助内容，请参阅 references/commands.md。

glab work-items <command> [flags]

glab work-items list [flags]
  --after        Cursor for pagination
  --group        Group/subgroup scope
  --output       text|json
  --per-page     Up to 100 items
  --repo         Project scope override
  --state        opened|closed|all
  --type         One or more work item types

glab work-items create [flags]
  --attach           Upload and reference a file; repeat for multiple files
  --confidential     Mark the work item confidential
  --description      Body text (use - to open editor)
  --description-file Read body text from a file or stdin
  --group            Group/subgroup scope
  --iteration        Numeric iteration ID
  --output           text|json
  --repo             Project scope override
  --title            Title for the new work item
  --type             epic|incident|issue|key_result|objective|requirement|task|test_case|ticket

glab work-items update <iid> [flags]
  --assignee         Update assignees
  --attach           Upload and reference a file; repeat for multiple files
  --description      Body text
  --description-file Read body text from a file or stdin
  --duedate          Update due date
  --group            Group/subgroup scope
  --iteration        Numeric iteration ID
  --milestone        Update milestone
  --output           text|json
  --repo             Project scope override
  --startdate        Update start date
  --title            Update title
  --weight           Update weight

glab work-items delete <iid> [flags]
  --group        Group/subgroup scope
  --output       text|json
  --repo         Project scope override