Documentation

1. What it does

Jira labels drift. Someone types front-end, someone else frontend, a third person FrontEnd, and a year later nobody can filter on any of them reliably. Jira Cloud gives administrators no screen for fixing this — you can add a label to an issue, but you cannot rename one, and you cannot remove one everywhere it appears.

Label Manager is that screen. It lists every label in your instance, tells you how many issues use each one, and lets you rename, merge or delete a label across every issue that carries it — in one action.

2. Installation & where to find it

Install Label Manager from its Atlassian Marketplace listing on your Jira Cloud site. Only Jira administrators can install apps.

Once installed, open it from the top Apps menu ("Label Manager"). There is nothing to configure — the app reads your labels the moment you open it. It runs as a full-screen page; there is no per-issue panel and nothing is added to your issue view.

3. The label list

The main screen is a single table: every label in the instance, sorted alphabetically and case-insensitively, with a checkbox, a usage cell and the actions available for it.

Filtering

The search box at the top narrows the list as you type. It filters what has already been loaded, in your browser — it never sends a request to Jira, so it is instant no matter how many labels you have. Clearing the box brings the full list straight back.

Selecting

Click a row's checkbox — or anywhere on its label pill — to select it. The checkbox in the table header selects or clears everything currently visible, so you can filter first and then select the whole filtered set. Selecting two or more labels enables Merge selected.

Refresh

Refresh re-reads the label list from Jira and discards anything the app was hiding locally (see section 9). Use it when you want Jira's raw answer rather than the app's post-edit view.

4. Usage counts

Counts are not loaded up front. Each row shows a small Count button; click it and the app asks Jira how many issues carry that label, then replaces the button with the number.

This is deliberate. An instance with a few thousand labels would need a few thousand queries to show every count, and you almost never need more than a handful. Once fetched, a count is cached for the rest of your session, so re-opening the same label costs nothing.

The cache is cleared after any rename, merge or delete, because those numbers are then out of date. The one exception is the label you just merged or renamed into: the app knows exactly which issues it wrote, so it shows that label's true count immediately rather than asking Jira for a figure that has not caught up yet.

Counts come from Jira's approximate issue count, and only include issues your own account is allowed to see (see section 11).

5. Renaming a label

Click Rename on any row. Type the new name and confirm. The app then finds every issue carrying the old label and rewrites that issue's labels: the old value is removed and the new one added, in a single update per issue. Every other label on the issue is left exactly as it was.

When it finishes you get a summary — Renamed "a" → "b" across N issues (M failed) — and the list refreshes.

Case-only renames

Renaming frontend to Frontend works. This is worth calling out because Jira treats the two as the same label when searching but as different values when storing — a naive implementation adds the new spelling without removing the old one and leaves both on the issue. Label Manager compares case-insensitively when deciding what to remove, so a case-only rename really is a rename.

Renaming onto a label that already exists

This is allowed, and it is simply a merge: issues carrying the old label end up with the existing one, and no issue gets it twice.

6. Merging labels

Select two or more labels and click Merge selected. The dialog lists what you picked; click any one of them to make it the target, or type an entirely new name. The chosen target is highlighted, so there is never any doubt about which way the merge runs.

Every source label is then removed from its issues and the target added. A source that is the target is skipped rather than pointlessly rewritten.

Reading the result

The reported total counts issues, not label-uses. If an issue carried two of the labels you merged, it is one issue in the result, not two. So merging a 3-issue label into a 1-issue label can legitimately give you 3 rather than 4 — that happens when one issue already had both. The number shown afterwards is the true size of the target label.

7. Deleting a label

Click Delete. The app first counts the affected issues, then asks you to confirm: "This removes 'x' from N issues. This cannot be undone." Only then does it remove the label from every one of those issues.

8. Label naming rules

These are Jira's rules, not the app's:

• No spaces. Jira labels cannot contain whitespace of any kind. The app blocks a name containing a space and tells you why, both in the dialog and again on the server before anything is written.
• Not empty. A blank name — or one that is only spaces — is rejected.
• Case is preserved but not distinguished in search. Backend and backend can both exist as stored values, and Jira's search will return issues for either when you query one. This is precisely the mess the app exists to clean up: merge them into one spelling.

9. Why the list can look out of date

This is the one behaviour worth understanding properly, because it looks like a bug and isn't.

Jira builds the instance-wide list of labels — and the issue counts, and every JQL search — from a search index, not from the issues directly. That index trails real edits, typically by seconds, sometimes by minutes on a busy site. Immediately after a bulk change, Jira will still happily tell you that the old label exists and that it is still used by N issues, even though the issues themselves have already been rewritten.

Left alone, that makes a perfectly successful rename look like it duplicated the label. Label Manager handles it like this:

• The result of the write is what counts. If every issue updated successfully, the app knows the old label is empty and hides it, regardless of what the index still reports.
• Labels you just created appear in the list immediately, before the index knows about them.
• The table footer tells you when something is being hidden, so the view is never quietly different from Jira's.
• Refresh clears all of that and shows Jira's unmodified answer. Do this a few minutes later and the index will agree with the app.

The same lag explains why a count you fetch seconds after a merge can look too low, and why a label you added to issues a moment ago may take a short while to appear if you open the app immediately afterwards.

10. What is not updated

Label Manager changes the labels field on issues. It does not — and cannot — rewrite places where the text of a label has been used as configuration elsewhere in Jira. After renaming or deleting a label, check anything that refers to it by name:

• Saved filters and JQL containing labels = "old-name".
• Board card colours configured with a label query, and board or quick filters.
• Automation rules that trigger on, or set, that label.
• Dashboard gadgets and reports built on a filter that mentions it.
• Anything outside Jira — Confluence macros, integrations, bookmarks.

These keep referring to the old string and will silently return nothing. Renaming a widely referenced label is worth a quick search of your saved filters first.

One thing you do not need to worry about: plain Jira labels have no colour of their own. Colours you may see on cards come from board card-colour rules or the separate Epic Colour field, so a rename cannot lose a label's colour — but a card-colour rule written against the old name will stop matching, per the list above.

11. Permissions

Every Jira request the app makes runs as you, never as a service account with elevated rights. That has two consequences worth stating plainly:

• You only ever see labels and counts for issues your account can browse.
• A bulk edit only touches issues you personally have permission to edit. Issues you cannot edit are reported as failures rather than being changed behind your back.

In practice this means the person doing the cleanup should be a Jira administrator, or at least hold Edit Issues across the projects being cleaned — otherwise a rename may only apply to part of the instance. The app tells you how many issues failed, and shows Jira's own error message for the first failure, so a permissions problem is visible rather than silent.

The app requests two scopes: read Jira work (to list labels and count usage) and write Jira work (to add and remove labels on issues).

12. Data, privacy & security

Label Manager runs entirely on Atlassian Forge — Atlassian's own hosting — and qualifies for the Runs on Atlassian badge.

• No external egress. The app makes no network calls to any server outside Atlassian. There is no backend of mine involved, because there is no backend of mine at all.
• No data stored. The app keeps no database and writes nothing to Forge Storage. Labels and counts are read when you open the page and discarded when you close it.
• No analytics or tracking inside the app.
• Your issues remain native Jira data throughout. Uninstalling the app changes nothing about them.

See the Privacy Policy, Terms of Service and DPA for the formal detail.

13. Limits

Behaviour	Detail
Bulk edit speed	Issues are updated one at a time, deliberately. A label on several thousand issues takes a few minutes; the progress indicator stays up throughout.
Rate limiting	If Jira rate-limits the app (HTTP 429), the same issue is retried up to three times, waiting as long as Jira asks. Operations slow down rather than fail.
Single failures	One issue that cannot be updated is counted as failed and reported; it never aborts the rest of the operation.
Leaving the page	A bulk operation runs from your browser session. Closing the tab mid-run stops it part-way — issues already updated stay updated. Re-run the same action to finish.
Newly created labels	A label used only by very recently updated issues may briefly not appear, until Jira's index catches up. See section 9.

14. FAQ

Can I undo a rename or delete?

No. There is no bulk revert. Each change is in the issue's history, but restoring across many issues would be manual. Check the usage count before confirming.

Why does the old label still appear right after I renamed it?

Jira's label index lags behind the edit. The issues are already correct — open one and look. The app hides the emptied label for you and says so in the table footer; press Refresh a few minutes later to see Jira's own answer.

Why is the merged total lower than the sum of the parts?

Because it counts issues, not labels. An issue that carried two of the merged labels is one issue in the result.

Can I create a label here?

Not directly — Jira has no concept of a label that exists without an issue. Renaming or merging into a new name effectively creates it on the affected issues.

Can labels have spaces?

No. That is a Jira restriction. Use a hyphen or underscore.

Does it work with Jira Service Management or Jira Product Discovery?

It reads and writes the standard Jira labels field, on whatever projects your account can see. It is built and tested for Jira Software. Jira Product Discovery's coloured option fields are a different field type and are not covered.

Does it change anything other than labels?

No. Each update sets the issue's labels field and nothing else. Note that editing an issue updates its "Updated" timestamp and appears in its history, as any edit does.

What happens to my data if I uninstall the app?

Nothing is lost, because the app stores nothing. Your labels are part of your issues and stay exactly as they are.

15. Support

Email [email protected] with any questions, bug reports, or feature requests. Support hours: Monday–Friday, 9:00–18:00 CET, with responses typically within one business day.