Labelkeep quick start

Your first label clean-up in Jira, step by step. Back to the Labelkeep product page.

Install (Jira Cloud)

In Jira, open Apps > Explore more apps, search for Labelkeep (once the listing is live), and choose Get app.
A site administrator approves three permissions: read issues, change issues, and the app's own storage inside Atlassian. Each one is explained on the product page.
Open Jira settings > Apps > Labelkeep.

Jira administrators work on the whole site from there. Project administrators use Project settings > Apps > Labelkeep instead (below). Everyone else sees a message naming the permission they need.

1. Find the labels to clean up

Wait for the counts. The line under the search box says how many labels were counted from how many labelled issues; on a big site it fills in over several passes.
Open Show possible duplicates in the "Possible duplicates" box, if there is one. It groups labels that differ only in capital letters, hyphens or underscores, such as checkout, check-out and Checkout, with each spelling's count. Merge into "checkout"… opens the merge for the whole group (step 2).
Or type part of a label in the search box, for example check, to see its spellings side by side; this also finds typos the duplicates box doesn't group. Click the Label or Issues column header to sort.
Tick the labels to work on. Then choose Delete…, Rename… (one label) or Merge… (two or more).

A label listed at 0 is one Jira still suggests but no issue you can see carries. It can't be deleted, because Jira Cloud has no API for that; it leaves Jira's suggestions once no issue uses it.

2. Preview and dry run

For a rename or a merge, type the new label. For a merge, the most-used selected label is suggested.
Leave Dry run on and choose Preview. The dialog says how many issues carry the labels and how many would change, and that this is a dry run.
Choose Run dry run. A panel at the top of the page shows the progress; you can leave the page while it runs.
The finished dry run says how many issues would change and that nothing was changed, with examples of each issue's labels before and after.

3. Run it for real

Choose Run for real on the finished dry-run panel. The same operation opens at its confirmation step, with dry run off and a fresh preview, in case the issues changed since.
Confirm. The operation runs in the background in batches of 20 issues, with a progress bar. You can close the page; open it again to see where it is.
The summary at the end gives the issues changed, the issues that needed no change, any that failed, and what a second search after the first pass found.

Only one operation runs at a time on a site. If another admin's operation is running, yours is refused with a message, and nothing starts.

Stopping a run

Choose Stop on the running operation's panel. The batch in progress (at most 20 issues) finishes, then the run ends with how many issues it checked and changed and how many were not touched. It is recorded as stopped in the Activity tab. Run the operation again to finish it.

When issues fail

One issue failing never stops the others. The summary's Issues that failed table names each one, with what Jira said and how to fix it. The usual causes:

What you see	What to do
Jira did not let the app edit the issue	In that project's permission scheme, give the role `atlassian-addons-project-access` (where Jira puts app users) Browse Projects and Edit Issues.
Jira would not set the Labels field	Check that Labels is not hidden in the field configuration of the issue's project and type, and that its workflow status allows editing.
The issue was deleted, moved or is hidden from the app	Nothing, unless the issue should be visible to the app; then check its issue security level.
Jira had a temporary problem	Run the operation again.

After a fix, run the operation again. Issues already changed need no change.

The Activity tab

Every operation, dry runs included, with when it ran, who ran it, the operation and labels, the scope, dry run or live, issues changed and failed, and its status. Project administrators see the operations on their own projects.

For project administrators

Open Project settings > Apps > Labelkeep in your project. The page works the same way, but lists only labels on issues you can see in that project, and operations change only those issues. Issues hidden from you, for example by an issue security level, are left out, and the summary says how many.

Your operations run in the background on your behalf. If Jira refuses that, for example because your account was deactivated mid-run, the run stops, says so and changes nothing more; open the app and run it again.

Before your first live run on a big label

There is no undo. Run the dry run and read its examples.
Watchers may get an email per changed issue: Labelkeep asks Jira not to notify them, but that is not verified. Try a small live run first.
On our test site, 280 issues took 37 seconds. Larger runs have not been measured; the progress bar shows how far a run has got.

Limits

Jira Cloud only, native Labels field only. No custom label fields, Confluence labels or Jira Data Center.
Up to 50 labels per operation. Labels can't contain spaces and are at most 255 characters.
Only issues the app can access are counted or changed: not archived projects, issues behind an issue security level that excludes the app, or projects whose permission scheme removed the app's role.
Jira's search index updates a few seconds after a change, so counts refreshed right after an operation may lag briefly.
The issue history shows the app as the editor; the Activity tab records who started the run.

Privacy

Labelkeep calls only your site's Jira API and sends nothing anywhere else. Its activity log and running operations are kept in Forge storage inside Atlassian. See the product page for what is stored.

Support

Email [email protected] with your site URL, what you ran (it is in the Activity tab) and the summary text.