← Relabel
DocumentationPrivacyEULASupport

Relabel documentation

Get started

  1. Install Relabel from the Atlassian Marketplace (Jira admin). Every site gets a 30-day free trial. After that it is $5.50 a month for up to 10 users, then billed per user.
  2. Open Jira settings > Apps > Relabel labels (or click Get started next to Relabel in Manage apps).
  3. Click Scan labels. Relabel reads the labels on every issue in every project, including labels-type custom fields, and counts how often each one is used. Nothing is changed. Large sites take a few minutes, and you can leave the page while it runs.

Project admins also get Project settings > Labels (Relabel): the same tool limited to their own project (see "Project settings page" below).

The page has four tabs: Labels, Suggested merges, Changes, and, for Jira admins, Settings.

Labels

After a scan you see every label in one list, 50 per page, with:

  • the label, and its field when you have labels-type custom fields,
  • how many issues use it,
  • Projects: the projects that use it and how often,
  • Last issue update: the most recent update of an issue with that label,
  • Rename, Delete and Issues (opens Jira's issue search for that label).

Narrow the list with Search (part of a label), Show (All labels, Used on one issue, No issue updated in 12 months), Sort (Most used, Least used, Name A-Z, Recently used, Oldest use, Most projects) and Field (All label fields or one field).

Tick several labels and click Merge selected, or tick one and click Rename or merge. Select labels from one field at a time.

Copy as CSV gives you the whole list to paste into a spreadsheet.

The list is a snapshot from your last scan. Changes made through Relabel update it straight away ("updated after later changes"). Labels added or removed in Jira after the scan show up when you click Rescan.

Suggested merges

Relabel groups labels that differ only by upper and lower case, dashes, underscores, dots, slashes, colons or a plural "s", for example backend, Backend and back-end. Each group shows the Spellings (issues) and a Suggested label (the most used spelling). Click Review merge to open the change dialog already filled in. Nothing changes until you confirm.

Different words with the same meaning, like perf and performance, are not grouped. Merge those yourself from the Labels tab.

Rename, merge or delete

The change dialog offers:

  • Rename it (one label): enter the New name.
  • Merge it into another label / Merge them into one label: enter the label to Merge into. It can be an existing label or a new one. Up to 50 labels per change.
  • Delete it (remove from every issue) / Delete them.

Options:

  • Only in these projects (keys, optional): for example WEB, MOB. Leave empty for all projects (up to 50 keys).
  • Include closed issues (Jira normally blocks edits there; the app is allowed to): some workflows block edits on closed issues. With this on, Relabel asks Jira to make the edit anyway. If Jira refuses, it falls back to a normal edit and lists any issue it couldn't change, with the reason.
  • Email watchers about each change (off: no notification storm): off by default, so watchers don't get an email for every issue.

New labels follow Jira's rules: no spaces (use a dash or underscore) and at most 255 characters. Labels with quotes, backslashes, brackets and other special characters can be renamed, merged and deleted like any other.

Matching is exact. Renaming TechDebt does not touch techdebt unless you select it too. If issues have a spelling that only differs in case, the preview tells you.

Preview, then confirm

Click Preview. Relabel finds every affected issue and shows:

  • how many issues will change and in which scope,
  • Issues per project, a count per selected label, and the first few issue keys,
  • how many issues already have the target label (they only lose the old one),
  • whether watchers will be emailed and whether closed issues are included.

No issue is edited yet. Click Change N issue(s) to run it, or Don't change anything.

While it runs

A progress bar shows issues changed so far. Click Run in background to close the dialog; the change keeps going and is listed in the Changes tab. Click Stop to stop it; what was already done stays done and can be undone.

Relabel saves its progress as it goes. If Jira rate-limits it or something is interrupted, it waits and continues without editing any issue twice. A change with no progress for a while shows as Paused, and Relabel restarts paused changes automatically every hour.

Changes and undo

The Changes tab lists every rename, merge, delete and undo, with who started it and its status: Preparing preview, Waiting for you, Changing issues, Done, Done with problems, Stopped, Cancelled or Paused. Click Details to see:

  • who started it, when it started and finished, and its scope,
  • how many issues changed, failed or were skipped, and Issues that were not changed with the reason for each,
  • Every issue as CSV: each issue with the labels removed and added,
  • Undo this change.

Undo this change is available for 90 days after a change finishes (or is stopped). It shows a preview first, then puts the old labels back on exactly the issues that were changed. Labels an issue already had before the change are left as they were. Each change can be undone once, and an undo can't itself be undone.

Project settings page

Project settings > Labels (Relabel) works the same way for one project:

  • It lists only labels on issues in that project that you can see.
  • Changes made there apply only to that project.
  • The Changes tab shows only that project's changes.
  • Include closed issues is only offered if a Jira admin allows it.

Settings (Jira admins)

The Settings tab on the admin page has:

  • Project admins can manage labels in their own project (Project settings > Labels): on by default. When off, the project page shows "Managed by your Jira admins".
  • Project admins may include closed issues: off by default.

Licensing and trials

Relabel is paid through Atlassian, with a 30-day free trial. If the subscription is not active, a Subscription not active banner appears. You can still browse the label list and past changes, but scans, previews, changes, undo and CSV exports are paused until a Jira admin renews in Apps > Manage apps.

Permissions and data

  • Relabel runs on Atlassian's Forge platform. It has three permissions (read issues, edit issues, app storage), no external network permissions, and sends nothing outside Atlassian.
  • The admin page reads labels across all projects as the app, so Jira admins see every label, including on issues they can't browse. The project page reads as the signed-in project admin.
  • Changes are made by the app, so issue history shows the app as the editor. Relabel records which account started each change and shows it in the Changes tab.
  • Relabel stores the label list and, for each change, the issues it touched and the labels removed and added (the undo record), in Forge storage for your site. Change records are deleted after 90 days.

Limits and known gaps

  • Up to 200,000 issues per change and 50 labels per change.
  • Jira doesn't let apps color labels on boards, so Relabel doesn't.
  • Labels used only in Jira Product Discovery or Confluence are not covered.
  • The label list is a snapshot: use Rescan to pick up changes made outside Relabel.
  • Issues opens Jira's own search, which ignores upper and lower case, so it may also show other spellings of the label.

FAQ

Why do I need an app? Can't Jira rename labels? Jira Cloud can't rename, merge or delete a label. The workaround is two bulk edits (add the new label, remove the old one), up to 1,000 issues at a time, with no undo. Relabel does it in one step for any number of issues, with a preview and an undo.

Will renaming delete my labels by mistake? No issue is edited until you have seen the preview and confirmed. Every change can be undone for 90 days.

Is the label list split into tiny pages? The list shows 50 labels per page, with search, filters and sorting, and a CSV export of everything.

What about labels with special characters? They work. Every label is quoted and escaped before it goes into a Jira search.

Can it change closed issues? Yes, with Include closed issues. Issues Jira still refuses are listed with the reason.

Will watchers get flooded with emails? Not unless you turn on Email watchers about each change.

Does it handle labels custom fields? Yes. Labels-type custom fields are scanned and changed separately from the system Labels field.

Can project admins see other projects' labels? No. The project page only shows labels on issues in that project that the person can see.

Big changes time out in other apps. What about here? Changes run in the background, save progress as they go and resume after interruptions.

Uninstalling and your data

Labels on your issues stay as they are. When the app is uninstalled, Atlassian deletes Relabel's stored data for your site, including undo records. Export Every issue as CSV for any change you want to keep a record of.

Support

Open a request in the Great Work support portal (linked from the Marketplace listing and from Get help in Settings) or email hello@greatwork.company. First response within 1 business day.