Labels

By the end of this page you will have given a project a short vocabulary of its own, pinned those words on the stories and bugs they describe, narrowed the backlog to one word, and renamed or retired a word without touching the items that carried it.

A label is a word a project pins on its work items: payments, tech-debt, client-asked. The vocabulary belongs to the project, so two projects may use the same word for different things and neither sees the other's list. Each word is unique within its project whatever its case, carries a colour so the backlog reads at a glance, and may carry a meaning in one line so two people pin it the same way. Labels are pinned from the item's editor and shown as chips on the backlog's rows and in the item's flyout; the backlog filters by one. A label is not an artefact: it carries no versions, and removing it unpins it everywhere without changing the items.

Before you beginCopy Anchor Link

Pin labels on an itemCopy Anchor Link

1. Open the backlog and open an item for editing, or press New Item.
2. Under Labels, pick the words that fit. The list is searchable; a word that does not exist yet is added from Manage Labels beside the heading, without leaving the editor.
3. Save the item.

The chips appear under the item's title on the backlog and under Labels in its flyout, in the label's colour. Up to twenty labels fit on one item.

Filter by labelCopy Anchor Link

Pick a word in the Any label filter above the backlog. The list narrows to the items carrying it, the choice is kept in the page's address so a link sent to a colleague opens the same view, and clearing the filter brings every item back. The filter appears once the project has at least one label.

Manage the vocabularyCopy Anchor Link

Press Manage Labels beside the Labels heading in an item's editor. The manager lists the project's words by name with how many items carry each, and offers three things to anyone who may edit the backlog:

• Add Label at the foot: a Word, a Colour from the palette and a Meaning; the word must be free within the project whatever its case. The new word is in every picker at once.
• Edit on a row rewrites the word, the colour or the meaning in place; every item carrying the label shows the new values at once, because an item points at the label rather than copying it.
• Remove on a row asks once, inline, then takes the word out of the vocabulary and off every item; the items are untouched. Keep backs out.

Viewers see the list and the counts without the form or the row buttons.

All the fieldsCopy Anchor Link

What happens nextCopy Anchor Link

• label.created, label.updated and label.deleted go out with the word and the colour; see the label.* events. Pinning or unpinning a label on an item announces nothing of its own: an item's labels travel with the item and are read back from the work items API as labels.
• A label is not part of an item's versions: restoring an earlier version of a story leaves its labels as they are, like its components.
• Heimdall and an agent connected over MCP read the vocabulary with list_labels before they draft or filter, and name labels by id when they list work items with label_id.

ManagingCopy Anchor Link

• Rename rather than replace: editing a word keeps it on every item; removing it and adding a new one starts from zero.
• A removed label disappears from every item and from the filter at once; the items keep their other labels and announce nothing.
• A deleted project takes its vocabulary with it.
• Client guests see the chips on the agreed items and may filter by them; they never shape the vocabulary.

Heimdall on this pageCopy Anchor Link

Heimdall reads a project's labels as part of its vocabulary and uses the words when it drafts or summarises the backlog; an agent connected over MCP reads them with list_labels and pins them through the stories it drafts. Neither coins, renames or removes a word: the vocabulary is the team's, kept short on purpose.

From the API and MCPCopy Anchor Link

PermissionsCopy Anchor Link

Frequently askedCopy Anchor Link

RelatedCopy Anchor Link

• Backlog — the items the words are pinned on
• Components — the other way items are grouped, by the part of the product they change
• Traceability — relations between artefacts, as opposed to words on them
• label.* webhook events