Work items

Overview

A work item is one piece of work — a bug, a story, a task, an epic — filed against a repository or a group, tracked through a status you name, and connected to the code that changes it. You file items, triage them into a status, assign them to people, group them under an epic, label them, put them in a milestone, and close them when the work lands. Because the tracker lives in the same place as the code, an item can be closed by a commit, moved by a merge, and reopened when the test that proved it fixed goes red again.

Everything on this page is available three ways: in the web app, from the gitmoap command line, and over the API — so a triage rota, a backlog import or a bot that files an item per alert is a script, not a browser session.

Quick start

Before you start

How it works

One shape, eight types

There is one kind of thing here — a work item — and its type decides where it may live, what it may contain, and which fields apply to it. An epic is not a separate product with its own screens; it is a work item whose type is epic.

Every type takes a title, a description, assignees, labels and relations. All but an epic also take acceptance criteria; all but a sub-task also take a milestone. The rest is the type table:

Three consequences catch people out. An epic can only live in a group, which is exactly why it can gather work from several repositories under it. A field the type does not declare is refused, not ignored — setting points on a bug is a 400 rather than a value silently dropped, so a broken script fails on its first call instead of on the day someone notices the number never arrived. And hierarchy is checked from both ends: spike, chore and sub_task are leaves that sit outside the tree entirely, so they take no children and cannot be given a parent.

Where an item lives, and what it is called

An item lives in a container: a repository or a group. Every task below therefore has two forms — one under /repositories/{repo_id}/… and a twin under /groups/{group_id}/… — and they behave identically apart from which types are legal there.

Its name is a number that counts within that container: #412 in one repository and #412 in another are different items, and &17 in a group is an epic. Numbers are allocated in order but gaps are normal — a deleted item leaves its number behind, so #412 never means "the 412th item filed". Moving an item to another container re-numbers it there; the response tells you the old and new names.

Status: the name you choose, the category we understand

A status has a name, which your team owns, and a category, which the platform owns. There are seven categories and they never change:

Rename "In Review" to "Ready for QA" and nothing breaks: boards still column it, a merge still drives it, and a rollup still counts it as not-done, because the platform reads the category and never the name. done and cancelled both close an item and only done completes it — a backlog cleared by mass-cancelling stale tickets must not look like a backlog cleared by doing the work.

A container may also constrain which categories may follow which. By default any status may move to any status, which is the setting most teams should keep.

Hierarchy and relations are different things

Hierarchy is containment — an epic contains stories, a story contains tasks. One parent, nesting capped at five levels, and cycles are impossible because the check walks the real parent links every time rather than a cached copy of them. Detaching has nothing structural to check, because it can only reduce depth.

Relations are dependencies and cross-references between peers — blocks, blocked_by, relates_to, duplicates. A relation is written on both items at once, so it can never half-exist, and it may cross containers freely. Nothing checks a relation for cycles: A blocks B blocks C blocks A is a real transient state during a refactor, so it is accepted. Be aware of what that costs while the blocker gate is on — two items that block each other cannot both be completed, and you break the deadlock by cancelling one, removing the relation, or turning the gate off for the container.

blocked the status and blocked_by the relation are deliberately not kept in sync. One is a human saying "I am stuck"; the other is a structural fact about which item has to land first.

Every change carries the version you read

A work item is edited by people and by the platform at the same time — a merge moves its status, a pipeline verifies its criteria, a commit message closes it. So an update names the version you read, and a mismatch is a 409 carrying the current state instead of a silently clobbered field. Re-read, re-apply, retry.

Settings are inherited from the group chain

Statuses, transitions, automation rules and defaults are configured per container and inherited field by field: for each setting, the nearest ancestor group that sets it wins, and anything nobody sets falls back to the platform default. A repository's own saved values count only while its Override group settings switch is on — with it off, the whole policy comes from the groups above, and the values the repository has stored sit dormant. The switch cuts the other way too: a group that turns its own switch on ends the walk there, so nothing below it can override what it sets.

Reading a repository's issue settings gives you the resolved answer; reading a group's gives you what that group itself stores. Removing a container's settings puts it back to full inheritance rather than resetting it to platform defaults.

How to

File a work item

Give it a title and a type. Everything else is optional: a description, a status, assignees, labels, a milestone, points, a severity, and a parent. Leave the type out and the container's configured default type is used, which starts life as Task; leave the status out and it lands in the status the container marks as the default for new work, which starts life as Triage.

The title is 1–255 characters and cannot be blank; the description is markdown up to 128 KiB. The milestone must already exist in this container, and every label you name must already be defined here or in a group above it — a key nothing defines is dropped on the way in, so although the create response echoes it back the item comes back without it on the very next read. Define the label first. If you name a parent, the parent's type has to accept this type and this type has to be one that takes a parent at all: an epic accepts almost anything, a story or a bug accepts tasks, and a spike, a chore and a sub-task neither hold children nor hang under anything.

Filing in a group works the same way and is where epics go:

Find the work items you need

The listing is newest-updated first and filters on status category, named status, type, assignee, label, milestone and free text. The filters combine, and the free-text search matches words in the title and the description as well as substrings of the title. Paging is by cursor: keep handing the next_token you were given back. A cursor is a position in the ordering, not a saved query — it carries no memory of the filters that produced it, so changing a filter mid-walk resumes at that position under the new filter rather than failing, and quietly skips whatever the new filter would have matched earlier. Start again from the first page instead.

The card view returns the same items enriched for display — the author and assignees with their avatars, the labels with their colours, the milestone, the comment count, the child counts and points, the verification state, and how many open items are blocking each one. Cards cost more per row, but they page exactly as the plain listing does: twenty at a time to a maximum of a hundred. The four filtered work-item listings — a repository's, a group's and the two personal ones — each have a card twin taking exactly the same filters. Reach for the plain form when you are scripting and the card form when you are drawing a board or a backlog.

A group listing spans the group's whole subtree — the items the group itself holds plus the work items of every repository and subgroup beneath it — and is the view to reach for when you want "every open bug in the org". Ask for scope=own instead to see only what the group itself holds.

See one work item

Track your own work

Two self-scoped listings need no container at all: what is assigned to you, and what you filed. Both span every repository and group you can reach, and both take the same status, type, label, milestone and free-text filters a container listing does. Both need a signed-in credential — they are keyed on who you are, so there is no anonymous form of them even for public repositories.

Rows are checked one repository at a time, not one container at a time. If your access to a repository is removed, its items leave these lists on the next read even though the assignment row is still there — which is the behaviour you want, and the reason a listing that spans containers is never trusted to the container's own verdict.

Change a work item

Send only the fields you are changing, plus the version you read — the version is not optional, and a body with no field in it at all is a 400. A title, description, status, milestone, points, severity and type can all move in one call. Assignees, labels, the parent and relations are not part of this call; each has its own action below.

Changing the type is not a rename. It re-checks everything the type governs: the container it is allowed in, the fields it declares, the parent it has, and the children it holds. Retyping a task that holds sub-tasks into a spike is refused, because a spike can hold nothing — detach the children first, then retype. Clearing a field is always allowed, so a type change can shed a field the new type does not have.

Changing the status is subject to whatever transition constraints the container declares. By default there are none.

Assign someone

Assignees are users or service accounts, and they must be members of the container — assigning somebody who is not is a 409, because work assigned to a person who cannot open it presents as a person ignoring their queue. Reading a public repository is not enough; real membership is what the check asks for. A work item carries at most five assignees, and the sixth is refused with a 400 rather than silently dropped. Assigning somebody who is already on the item changes nothing and is not an error.

Unassigning is the mirror, and it is the one write anybody can do to themselves without Developer access: if a work item lands on you and is not yours, you can take yourself off it.

Define the labels a team uses

A label is defined once per container and applied many times. The key is its identity and is fixed; the colour and description are the only two things an edit can change. A key is 1–64 characters of lowercase letters, digits and hyphens, starts with a letter or a digit, and may carry one :: separator — and that separator is the useful part. The colour is a six-digit hex triple such as #d73a4a.

A key with a :: is scoped: priority::low, priority::medium, priority::high all share the prefix priority, and a work item may carry at most one label per prefix. Applying priority::high to an item already carrying priority::low replaces it in one step; the item is never briefly unprioritised and never carries two. That turns a bag of free-form strings into a field with a domain, without anybody configuring a custom field.

Labels defined on a group are visible to every repository beneath it, so an org-wide priority::high is defined once at the top. A repository may define the same key to override its colour locally — the nearer definition wins when the label is applied. A key that already exists in the same container is a 409; edit that one instead.

Changing how a label looks is one edit and touches nothing else:

Every work item carrying one of a container's own labels is one call, and a key the container does not itself define answers 404 rather than an empty list, so a typo does not read as an unused label:

Put a label on a work item

A work item carries at most ten labels. The label has to be defined in the container or in a group above it — an undefined key is a 400, not a new label, because minting label vocabulary is a Maintainer's decision and applying it is a Developer's.

Taking off a label the item does not carry is not an error — the item comes back unchanged — so a cleanup script does not have to read the item first to know whether the call is safe.

Plan a milestone

A milestone is a dated commitment inside one container: a title, an optional description and an optional due date, which is a calendar day such as 2026-09-23 with no time or time zone. Titles are unique within the container, so a second milestone called "Q3" in the same repository is a 409.

The container's milestones are one call, newest created first, open and closed alike, with a search fragment that matches the title and the description:

Closing a milestone is an ordinary edit — set it closed — and it does not touch the work items in it. What it does do is stop new work being added: putting an item into a closed milestone is refused.

Put work in a milestone and track it

A work item may only join a milestone its own container defines — a repository item takes a repository milestone, a group epic takes that group's milestone. Naming a milestone from somewhere else answers 404, because a milestone that could not read its own members would report progress that was quietly missing them. A sub-task takes no milestone at all.

Reading a milestone gives you its progress computed from the live work items in it, not from a stored counter: the total, how many are open, how many completed and how many cancelled, and the points completed against the points total. There is no snapshot to go stale, and two people with different access legitimately see different numbers, because the figures only count the items each of them may see.

The milestone's work items are also a listing of their own. It takes no filters and no paging — it returns every item in the milestone in one response, so a milestone holding thousands of items answers with a large body. To filter, order or page them, use the milestone filter on the ordinary work-item listing instead.

Break work down into a hierarchy

Set a parent and the item becomes its child. The parent may be in another container — an epic in a group adopting a story in a repository is the whole reason the hierarchy is shaped this way — and you need Developer access on both ends, because the write touches both.

Four rules govern the move, and each of them is checked against what is really there:

• The child's type has to take a parent at all. spike, chore and sub_task do not, and asking is a 400 before anything else is looked at.
• The parent's type must accept the child's type. The matrix is a property of the parent, so it is asymmetric: an epic parents nearly everything, a story or a bug parents tasks, an incident parents tasks, and a task, spike, chore or sub-task parents nothing.
• Nesting is capped at five levels, and the cap has to hold for the deepest item in the subtree you are moving, not just the one you named — a three-deep subtree cannot go under a three-deep parent.
• No cycles. An item cannot become its own ancestor.

Setting the parent an item already has changes nothing and is not an error. Detaching has no structural rule to satisfy — it can only reduce depth — so it is never refused on those grounds, though it still needs Developer access in the old parent's container, because it writes there too. The subtree comes with the item, and a subtree of more than 1,000 items is refused as a conflict rather than moved in pieces; move its branches separately.

See how an epic is tracking

A rollup counts an item's direct children — not the whole subtree beneath it: how many there are, how many are open, completed and cancelled, and how many points are done against the total. Completed means done only — cancelled work closes without completing, and folding the two together is what turns a delivery metric into a lie. The same figures ride every card, so a backlog view already shows them without a second call.

An epic lives in a group, so an epic's rollup is the group form — and it is the interesting one, because its children are spread across the repositories beneath the group rather than sitting in one of them:

A rollup only counts the children you can see. If an epic in a public group has children in a private repository, someone outside that repository sees a smaller total — and no "hidden" count, because a hidden count is itself the disclosure.

Record that one item blocks another

There are four kinds of relation: blocks and its mirror blocked_by, and the self-mirroring relates_to and duplicates. You name one direction and both rows are written together, so the far item shows the connection immediately and the pair can never half-exist.

You need Developer access on both items, not just on the one in the URL, because the write puts a row on each. An item cannot be related to itself, and adding a relation that is already there is a 409, so read the item before retrying rather than treating the error as a failure to write.

The blocked_by relation has teeth, and this is the one completion gate that is on by default: a work item with an open blocker cannot be completed. Cancelling it is deliberately still allowed — "this is blocked" and "we are not doing this" are not in conflict, and a gate that made you unblock work before you could abandon it would only teach people to delete the relation.

Close a work item

Closing takes an optional status: leave it out and the container's default completed status is used, or name a status yourself to distinguish "we did it" from "we are not doing it". The status you name has to be a closed one — an open status is a 400, because closing into In Progress is not a thing anybody means.

Two gates can refuse a completion, and both are container settings. Open blockers is on unless a container turns it off: an open blocked_by refuses the completion. Acceptance criteria is off unless a container turns it on: with it on, an item with a required criterion that is not satisfied will not complete. Both gates apply to completing, never to cancelling. Both are also skipped by an ordinary update that happens to set a closed status, so use the close action when you want them enforced.

Work items also close themselves, unless the container turns the commit keyword off. A commit message saying Closes #412 on the default branch closes the item, and so does merging a merge request that says the same thing in its own title or description. Merely naming a work item never closes it — a merge request that references #412 without a closing keyword moves it into the review category when it opens, and no further. If that commit later turns out to be in no branch at all — force-pushed away, or on a branch deleted unmerged — the item comes back to the status the commit found it in, because a fix that is not in the product is not a fix.

Reopen a work item

Leave the status out and the item returns to the container's default status for new work; name one yourself and it has to be an open status, because a reopen into Done is not a reopen. Reopening puts the item back into the container's open-item count, so it can be refused if the container is at its limit, and it is subject to the same transition constraints an ordinary status change is. A closed item whose bound test regresses on the default branch also reopens itself, carrying the range of commits that broke it.

Move a work item to another repository or group

A move is a re-key, not a copy: the item keeps its discussion, its activity, its children, its parent, its relations and its criteria, and arrives with a new number in the destination. The response names the old reference and the new one. Naming the container it is already in is a 400, not a no-op.

Three things do not come along, and the response tells you about each:

• The milestone. A milestone belongs to one container and cannot follow the item out of it.
• Any label neither the destination nor a group above it defines. A label the destination inherits from an ancestor group survives the move; one that exists only in the container the item is leaving does not.
• The number. #412 becomes something else, and links to the old number do not follow.

You need Maintainer at the source — the item is leaving, and its number is retired — and Reporter at the destination, because arriving is a create there. The destination has to accept the item's type, and it has to have room under its own open-item limit.

Delete a work item

An item that still has children is refused, and the refusal says how many there are. Reparent or delete them first, so that orphaning a subtree is a decision somebody makes rather than a side effect of somebody else's delete.

Change the statuses and automation a container uses

Issue settings carry the status set, the transition constraints, the type a create defaults to, whether commit keywords close work and on which branches, whether a public container accepts filings from non-members, the automation that git events drive, and the gates that guard completion. The write is a merge, not a replacement: a field you leave out of the body is left alone, and a field you send as null is cleared so it inherits again. A body with no field in it at all is a 400.

The same settings body carries three groups of fields this page does not cover, because they belong to the features they configure: what a TODO: marker in the code becomes and which paths the scanner skips, what happens when the code under a work item's anchor changes beyond recognition, and whether green acceptance criteria close an item on their own. Those are in Linking work to code and Proof of Done. They are all one merge into the same body, so a script that sets a status set and a TODO policy sends one call.

Set the same policy on a group and every container beneath it inherits it, which is how an org-wide status set or completion gate is defined once. Turn the group's own Override group settings on and the containers below it can no longer override the fields the group sets — that is what makes the policy enforceable rather than advisory.

Two rules shape what you can do to a status set:

• A status's category cannot change once the status exists. Add a new status in the category you want and archive the old one; work already in the archived status keeps rendering, sorting and rolling up correctly, and only disappears from the pickers.
• A set must stay usable. At least one unarchived completed status, at least one unarchived open one, exactly one unarchived status marked as the default for new work and that one open, unique ids, and between 1 and 30 statuses in a set.

A group's settings read back what that group itself stores, unresolved, rather than an effective answer — a group is what the containers below it inherit from, so what it stores is the interesting question. A field this group leaves unset comes back empty here and is supplied by its own parent.

Go back to inheriting

Removing a container's issue settings deletes what it stores and puts it back to full inheritance from the group chain. Nothing about the work items changes — an item in a status the inherited set does not name keeps that status and keeps behaving correctly, because its category is on the item.

The same action on a group hands the group back to its parent, and takes with it any lock the group was holding over the containers below.

Reference

Almost every operation has a repository form and a group form, taking the same body and answering the same shape. Three differences are worth remembering, and each is explained in the task above that it belongs to: which work-item types a container accepts, how far a group listing reaches, and whether issue settings come back resolved or raw. The four personal listings are the exception — they belong to you rather than to a container, so they have neither form.

Work items in a repository

Work items in a group

Your own work

Assignees