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. ```bash # 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. ```bash 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: ```bash 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 ```bash # 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 ```bash # 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. ```bash # 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 ```bash # 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 ```bash # 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](references/commands.md). The synopsis below is authored guidance, not exact binary output. ```text 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 ```