ArdSaor

Label Doctor for Jira — Documentation

Label Doctor helps teams clean up Jira labels fast by finding duplicates, consolidating variants, and keeping label hygiene effortless.

Supported Products

  • Jira Software (Cloud)
  • Jira Service Management (Cloud)
  • Jira Work Management (Cloud)
  • Works in both Company‑managed and Team‑managed projects

Permissions & Data

  • Required scopes: read:jira-work, write:jira-work, read:jira-user, storage:app
  • Data handled: label strings and issue keys used for previews/updates
  • Hosting: Built on Atlassian Forge (no external servers)
  • Storage: Minimal app storage for ignore rules, scan metadata, and undo snapshots

Installation

  1. Install from the Atlassian Marketplace (Jira Cloud).
  2. The app adds a Jira admin page: Label Doctor – Duplicate Label Cleaner & Manager.
  3. Open the page to scan and manage labels.

Quick Start

  1. Open Label Doctor from Jira's Apps or Admin menu.
  2. Optionally enter a space/project filter (comma‑separated keys) to scope the scan.
  3. Click "Scan labels".
  4. Review groups and take action (Merge or Search & Replace).

Scanning

  • Scope filter: e.g., "PX, ENG" to limit to specific projects. Leave blank to scan all labels.
  • Smart detection: Label Doctor uses intelligent detection to find exact duplicates, near‑matches (typos, casing, punctuation), and numeric variants.
  • Caching: Recent results may be shown for speed. Rerun a scan to refresh after changes.
  • Scale: Designed for large projects with paginated collection; by default up to 2,000 issues per scan window to keep UI responsive.

Understanding Results

  • Label group: A canonical suggestion plus related variants.
  • Confidence badges:
    • Exact: clear duplicate (e.g., “Test” vs “test”)
    • Near: likely duplicate (e.g., “Tset”, “Test!”)
    • Numeric: differs only by numbers (if enabled)
  • Sample issues: Quick links to spot‑check impact.
  • Scan details: Runtime, scope, and summary stats for transparency.

Merge Duplicates

  1. Open a label group and choose the canonical label (default suggestion provided).
  2. Review variants included in the merge.
  3. Optional: Click “Dry‑run preview” to see the change set.
  4. Click "Start merge" to apply:
    • The canonical label is added to affected issues.
    • Variant labels are then removed.
  5. Progress shows live updates; you can leave the page and return later.

Ignore Variants

  • Click “Ignore this label variant” on a variant you don’t want to include in future merges.
  • Ignored variants remain visible but are excluded by default.
  • You can unignore at any time.

Undo

  • After a merge or replace, an "Undo available" banner appears for a limited time window (24 hours). Use it to revert the last operation safely.
  • The banner shows how much time remains before the undo option expires.

Search & Replace

Use Search & Replace for quick, targeted renames outside of duplicate groups.

  1. Select the existing label.
  2. Enter the new label.
  3. Click “Preview replacement” to review scope and sample issues.
  4. Click “Start replace” to apply changes in bulk.
  5. Undo is available for a limited time via the banner.

Best Practices

  • Use previews for large merges or replacements.
  • Scope scans by project keys when cleaning a specific area of Jira.
  • Keep a short list of "approved" canonical labels and ignore variants you intentionally allow.
  • Review near‑match suggestions carefully before merging—smart detection may surface similar but intentionally distinct labels.

Troubleshooting

I don’t see results for some projects

  • Ensure you have “Browse Projects” permission in those projects.

Merges or replacements fail

  • You need “Edit Issues” in the affected projects.

Results look stale

  • Click “Scan labels” again to refresh cached results after changes.

Security & Privacy

  • Runs entirely on Atlassian Forge.
  • No customer data is sent to external services.
  • Only minimal metadata is stored: ignore rules, scan summaries, and undo snapshots.

FAQ

Does it work with Jira Service Management?

Yes. It supports Jira Software, Service Management, and Work Management (Cloud).

Will it change any fields other than labels?

No. Only labels are added/removed as part of merges or search & replace.

Can I undo changes?

Yes. An undo banner appears after actions and remains available until the listed expiry time.

Support

Need help or have a feature request? Contact us via the Marketplace listing support link. Include your site URL and a short description of the action you were taking.