glab-workitems

glab work-items

Create, list, and delete GitLab work items — GitLab's unified work tracking model for tasks, OKRs, key results, epics, incidents, test cases, and related planning objects.

Parent hierarchy

create and update accept --parent <reference>. A positive IID (42 or #42) resolves in the child's project/group scope; qualified references such as group/project#42 or group&42, and issue/work-item URLs, can select another namespace on the same instance. Quote references containing # or & in shell examples. glab resolves the parent to its global work-item ID and rejects URLs whose configured API host differs from the child's API host. Confirm the child, parent, host routing, and intended hierarchy before approving the write; server permissions and hierarchy rules still apply. Omitting the flag leaves the parent unchanged on update; an empty string is not a remove-parent operation.

# After approving the hierarchy change
glab work-items update 42 --parent 'group/project#40' --repo group/project

Date filters

list supports --created-after, --created-before, --updated-after, --updated-before, --closed-after, --closed-before, --due-after, and --due-before. After bounds are inclusive; before bounds are exclusive. Values accept YYYY-MM-DD, RFC 3339 with offset, or signed relative offsets such as -7d, 2w, -1m, and 1y (days/weeks/months/years, amount -9999 through 9999). Relative dates are evaluated by the server relative to today; date-only absolute values use the server's time zone. Use explicit-offset timestamps when reproducible boundaries matter.

Date filters require GitLab 19.4 or later; relative dates require GitLab 19.6 or later. A closed-date filter implies --state closed unless state was explicitly supplied; --state all is allowed, --state opened is rejected. Date arguments are only sent when specified, so an older server can still accept an unfiltered query but may reject a requested filter. Cursor pagination repeats the filters; relative bounds can move between runs.

glab work-items list --group group/subgroup --created-after=-7d
glab work-items list --repo group/project --due-after 0d --due-before 2w

Assign an iteration

Use the numeric iteration ID with --iteration on create or update:

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

Omitting the flag leaves the iteration unset on create and unchanged on update. Verify the work item's scope and the intended iteration before the write; do not substitute an iteration title for the ID.

⚠️ Experimental Feature

glab work-items is still marked EXPERIMENTAL upstream:

• command shape may still change
• availability can differ by GitLab version / feature flags
• some work item types are only meaningful at group scope
• use glab issue for stable day-to-day issue workflows

See: https://docs.gitlab.com/policy/development_stages_support/

Quick start

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

Scope model

glab work-items uses repository context by default, then lets you override scope explicitly:

• Current repo context → project work items in the checked-out repository
• --repo owner/project → a different project
• --group my-group → group/subgroup work items

This matters because some work item types are commonly project-scoped (task, issue, incident) while others often live at group scope (epic, objective, key_result).

Common workflows

List work items

# 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

Create work items

Use --type to declare the work item type explicitly.

# 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

For one-off multi-line descriptions, use --description-file <path> or --description-file - for stdin. It is mutually exclusive with --description. A file containing exactly - is rejected because --description - means "open an editor".

The experimental --attach <path> flag uploads a file and appends the returned Markdown reference to the description. Repeat it for multiple files, or use --attach - for one stdin attachment; do not also read a description from stdin. On update, attachment-only input preserves the current description and appends references, while an explicit description replaces the body first. Uploads are project-scoped, so --attach cannot be combined with --group.

Supported upstream type values include: epic, incident, issue, key_result, objective, requirement, task, test_case, and ticket.

Delete work items

# 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 is destructive. Double-check whether the IID belongs to the intended project or group before running it.

Update work items

# 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

Work items vs issues

Need	Prefer
Standard bug / feature issue workflow	glab issue
Tasks, OKRs, objectives, key results, next-gen epics	glab work-items
Stable/non-experimental issue automation	glab issue
Group-scoped planning objects	glab work-items --group ...

Use glab work-items when the work type itself matters. Use glab issue when you just need standard issue lifecycle commands with the most mature CLI surface.

Troubleshooting

work-items: command not found or docs show workitems:

• The current upstream command family is glab work-items with a hyphen.
• Unhyphenated glab workitems examples are stale.
• Check your version with glab version when troubleshooting local command availability.

Create/delete seems unavailable on your machine:

• Confirm local command availability with glab work-items --help and upgrade glab if create/delete subcommands are missing.

Type filter returns nothing:

• Not every GitLab instance exposes every work item type.
• Try the correct scope (--group vs --repo) for the type you're querying.

Delete removed the wrong thing:

• delete works by IID within the selected project/group scope.
• Re-run with explicit --repo or --group so the scope is unambiguous.

Related Skills

• glab-issue — Standard issue workflows
• glab-milestone — Milestones often paired with OKRs and planning
• glab-iteration — Sprint / iteration planning
• glab-incident — Incident-specific workflows

Command reference

For complete captured help, see references/commands.md. The synopsis below is authored guidance, not exact binary output.

glab work-items <command> [flags]

glab work-items list [flags]
  --after        Cursor for pagination
  --created-after / --created-before  Creation date bounds
  --updated-after / --updated-before  Update date bounds
  --closed-after / --closed-before    Closure date bounds
  --due-after / --due-before          Due date bounds
  --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
  --parent           Parent IID, qualified reference, or same-instance URL
  --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
  --parent           Parent IID, qualified reference, or same-instance URL
  --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