# Glab Workitems

> Create, list, update, and delete GitLab work items (tasks, OKRs, key results, epics, incidents, test cases). Use when working with GitLab's work item types beyond standard issues. Triggers on work items, work-items, tasks, OKRs, key results, epics, work item create, work item update, work item delete.

- Skill: `vince-winkintel/glab-workitems` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add vince-winkintel/glab-workitems`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vince-winkintel/glab-workitems/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: vince-winkintel (https://skillmd.com/u/vince-winkintel)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/vince-winkintel/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.

## ⚠️ 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

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

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 for affected commands, see [references/commands.md](references/commands.md).

```text
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]
  --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
  --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
  --description      Body text
  --description-file Read body text from a file or stdin
  --duedate          Update due date
  --group            Group/subgroup scope
  --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
```