Managing Issue Labels

Labels are the free-form words your team groups Issues by — the one Issue Tracker vocabulary that isn’t a status, a type or a priority. Settings → Issue Tracker → Labels is where they live: a single place to see every label the workspace has, colour it, reorder it, rename it, or delete it.

Before you start

• The Issue Tracker module has to be switched on for your workspace. If it isn’t, the Issue Tracker entry doesn’t appear in Settings at all.
• Reading the tab needs the View issues permission. Changing anything — adding, renaming, recolouring, reordering, deleting — needs Manage issues (status, priority, assignee, triage, labels), or workspace-owner rights. Without it the tab is read-only: no add button, no edit or delete buttons, and dragging is disabled.

Opening the Labels tab

Go to Settings, find Issue Tracker under the Modules heading in the sidebar, and select the Labels tab. The tabs on that screen run General, Statuses, Types, Priorities, Labels, Copy Issue Summary.

Each row shows the label as it actually renders — its name in its own colour — along with how many Issues currently carry it, a drag handle, and Edit and Delete buttons. A workspace with none yet reads “No labels yet.”

Creating a label

Use Add label at the top of the Labels card. It opens a New label pane with two fields — Name and Colour — and the save button in that pane also reads Add label. A new label joins the end of the list; drag it where it belongs afterwards.

Two rules can refuse a name:

• A word the workspace already uses. Names are unique, so a second “Billing” is refused with The label “Billing” already exists.
• A name that collides with a managed field. A type, priority, status or triage prefix — type:bug, priority:critical, status:planned, module:voice, triaged and the like — belongs to a column the Issue already has, and a label wearing one would save and then render nowhere. It’s refused on both ways in with a single sentence: That name belongs to a field the Issue already has — pick a word that is not a type, priority, status or triage prefix.

A label name can be up to 100 characters.

Colour

Colour is picked in the New label and Edit panes, from a palette of eleven swatches — the same palette the Statuses, Types and Priorities tabs offer, so a colour means the same thing everywhere in the tracker. The pane previews the chip as you pick. There is no swatch to click on the row itself; open Edit to recolour.

Colour is purely visual: it doesn’t change which Issues the label is applied to.

Renaming

Click Edit on a label’s row, change the Name, and save. Because an Issue’s link to a label points at the label’s row, not its name, renaming doesn’t touch which Issues carry it — every Issue that had the old name now shows the new one, automatically, with nothing to reapply.

The one thing a rename can break is anything that names the label by its word rather than its row. Filtering Issues by label over the API matches on the name — GET /api/v1/issues?label=Billing — so a saved query, report or integration spelling out the old word stops matching once the name underneath it changes. (The tracker’s own filter bar has no label filter, so there is no in-app label-filtered URL to worry about.)

Reordering

Drag a label row up or down to change its position. This is the order the label box on an Issue offers its options in, and the order this tab lists them in.

It’s a display preference and has no other effect — in particular, the label chips shown on an Issue itself are always listed alphabetically, so reordering here doesn’t change those.

Deleting

Deleting a label removes it — and only it. Unlike deleting a status, type, or priority, deleting a label does not ask you to pick a replacement, because there’s nothing to reassign: an Issue with no label is still a perfectly complete Issue. The word comes off every Issue that had it at the same moment the row goes, so the confirmation tells you how many Issues carry it and that none of them are deleted, rather than where they’re going. Confirm with Delete label.

Every label is deletable. Statuses, types and priorities include seeded rows that can be renamed and recoloured but never removed; labels have no such rows.

This can’t be undone — if you need the label back, you’ll need to recreate it and reapply it to those Issues by hand.

The 100-label cap

A workspace can have at most 100 labels. Once you’re at the cap the Add label button is disabled, with the reason on hover: A workspace can have 100 labels. Delete one before adding another.

The cap is enforced on the server on both ways a label can be born — this tab, and the API — so a request that would create label 101 is refused with the same sentence rather than quietly slipping past.

Creating a label from an Issue

The Labels field on an Issue offers the words the workspace already has; typing a word it has never used returns “No results found” rather than creating it, so new labels are added from this tab.

The other way in is the API: POST /api/v1/issues/{number}/labels with a label the workspace hasn’t used before creates that label as it attaches it. A label born that way is the same row this tab edits — it joins the end of the list and is tinted with the next colour in the palette — so it looks no different from one someone deliberately set up, and you can come back to Settings → Issue Tracker → Labels to recolour, rename, or reorder it like any other. The same two naming rules and the same 100-label cap apply on that path.