Skip to main content
skill CX Codex

glab-workitems — Claude Code skill for GitLab work items

The glab-workitems Claude Code skill creates, lists, updates, and deletes GitLab work items. It activates for requests about tasks, OKRs, epics, and other work item types.

MIT 120 installs ★ 51 updated 2026-10-20

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add vince-winkintel/gitlab-cli-skills --skill glab-workitems -a claude-code
Open on GitHub

What glab-workitems does

The skill manages GitLab records through glab work-items, including creation, listing, updates, and deletion. It covers tasks, epics, incidents, OKRs, key results, test cases, and other work item types. Scope comes from the current repository or can be set to a project or group.

GitLab marks glab work-items as experimental, so its command shape and availability depend on the GitLab version and feature flags. Date filters require GitLab 19.4 or later; relative dates require GitLab 19.6 or later. The source recommends glab issue for routine work with standard issues.

What it helps with

  • create a task or epic in a project or group
  • find work items by type and state
  • filter records by creation or closure date
  • update or delete a work item by IID

Example prompts for the agent

  • Create a project task titled “Check the failing pipeline.”
  • List open epics in the gitlab-org group.
  • Find work items created in the last -7d.

How to install glab-workitems

1Skills CLI (Vercel)

npx skills add vince-winkintel/gitlab-cli-skills --skill glab-workitems -a claude-code

2Manually: put the files in place

~/.claude/skills/glab-workitems/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/glab-workitems/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about glab-workitems

How do I install glab-workitems in Claude Code?

Run npx skills add vince-winkintel/gitlab-cli-skills --skill glab-workitems -a claude-code. The skill file is at ~/.claude/skills/glab-workitems/SKILL.md.

What does glab-workitems do?

It manages GitLab work items with glab work-items: creating, listing, updating, and deleting records such as tasks, epics, and incidents.

Which GitLab versions support date filters?

Date filters need GitLab 19.4 or later. Relative date values need GitLab 19.6 or later.

Source text

SKILL.md · MIT
---
name: glab-workitems
description: 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.
---

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

© vince-winkintel · MIT · vince-winkintel/gitlab-cli-skills

Similar skills

All skills for Notes, tasks and projects →

From the same set45

The whole set →
glab-packages Gives the agent the glab packages command surface: list registry entries, upload a file, fetch a version, remove a package. CX Codex +1 123installs glab-help This skill explains glab help syntax and guides you through command and subcommand help in the GitLab CLI. CX Codex +1 122installs glab-user The glab-user skill lets an agent inspect GitLab user data and events through glab. Use it when a chat-based check of account activity is enough. CX Codex +1 121installs glab-container-registry glab-container-registry operates GitLab container registry repositories and tags via glab CLI. Useful for tag metadata inspection and scheduled image cleanup. CX Codex +1 121installs glab-token The glab-token Claude Code skill manages GitLab access tokens, including creating, revoking, and rotating them. The agent activates it for requests about PATs or API tokens. CX Codex +1 120installs glab-version glab-version — a small skill that reports which glab CLI build is installed. Useful when a command misbehaves and the version is the first thing to rule out. CX Codex +1 120installs glab-opentofu glab-opentofu — a Claude Code skill for managing OpenTofu and Terraform state in GitLab. It activates for backend setup and infrastructure-as-code tasks. CX Codex +1 119installs glab-label The glab-label Claude Code skill manages GitLab labels at project and group level. It responds to requests to create, inspect, edit, or remove labels for issues and merge requests. CX Codex +1 118installs

Project sponsors

Companies that keep this analytics open