glab-workitems

Q: How do I install glab-workitems?

Run npx skills add https://github.com/vince-winkintel/gitlab-cli-skills --skill glab-workitems in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/glab-workitems/ (personal) or .claude/skills/glab-workitems/ (project).

by vince-winkintelTesting & QA

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.

Installs: 102
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/vince-winkintel/gitlab-cli-skills --skill glab-workitems

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads glab-workitems automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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.

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 for affected commands, see 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

FAQ

What does the glab-workitems skill do?

How do I install glab-workitems?

Run npx skills add https://github.com/vince-winkintel/gitlab-cli-skills --skill glab-workitems in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/glab-workitems/ (personal) or .claude/skills/glab-workitems/ (project).

Which AI agents can use glab-workitems?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is glab-workitems safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains glab-workitems?

It is published by vince-winkintel in vince-winkintel/gitlab-cli-skills. It has 102 recorded installs.