Tracking Technical Debt in Jira: Labels vs. a Custom Select Field

Your team keeps filing debt tickets, but six months later nobody can answer a basic question: how much debt do we actually carry, and where? The answer usually fails not because the tickets are missing, but because the categorization mechanism was chosen casually. In Jira, the realistic choice is between labels and a custom Select List field, and the two behave very differently once you try to report on them.

The decision and its constraints

Decide based on three constraints:

• Who needs to add values? Any user can apply a label. Only a Jira administrator can create a custom field or change its options.
• How clean must the data be? Labels accept free text, so tech-debt, techdebt, and tech_debt coexist silently. A Select List restricts users to predefined options.
• What reporting do you need? Dashboard gadgets (pie charts, two-dimensional filter statistics) group far more reliably by a single-select field than by labels, where one issue can carry several values and typos fragment the counts.

Comparison at a glance

Trade-offs in practice

Labels win when the taxonomy is still moving. If your team is discovering what kinds of debt it has — migration work, flaky tests, dependency upgrades — forcing an admin round-trip for every new category will kill adoption. The cost shows up later: a JQL query like labels = tech-debt silently misses every issue tagged techdebt, and there is no global rename, so cleanup means bulk-editing each issue.

A Select List wins once the taxonomy stabilizes and someone — a lead, a PM, an auditor — needs trustworthy numbers. Renaming an option updates every issue that uses it, and gadgets group cleanly. The costs are the admin bottleneck and screen clutter: every custom field you add appears on create/edit screens for its context, and a field-happy instance becomes slower to administer and more confusing for users. Keep the option list short (5–8 values) and scope the field's context to the projects that need it.

A common hybrid: use a label like debt as a coarse marker anyone can apply, and a Select List such as Debt Category (values: architecture, dependencies, test-coverage, docs) that a triage session fills in weekly. The label captures volume; the field powers reporting.

Concrete implementation

To set up the field, you need Jira administrator permission:

1. Go to Settings → Issues → Custom fields → Create custom field and choose Select List (single choice).
2. Name it Debt Category and add your options.
3. Limit the context to the relevant projects rather than Global, and associate it only with the screens those projects use — this avoids cluttering every team's create dialog.

Then validate, in the issue navigator (any user can run these):

-- Coarse volume check (labels)
project = PLATFORM AND labels = debt

-- Structured reporting check (custom field)
project = PLATFORM AND "Debt Category" = architecture

Compare the two result sets. Issues in the first query but not the second are untriaged; issues with a category but no label reveal inconsistent process. As a data-quality check, run labels in (tech-debt, techdebt, tech_debt) — if more than one variant returns results, that is concrete evidence of label fragmentation. Finally, add a Pie Chart gadget to a dashboard grouped by Debt Category and confirm the counts match your JQL totals.

Limitations

These behaviors reflect long-standing Jira (Cloud and Data Center) functionality, but menu paths and gadget availability differ between deployment types and versions — verify against your instance. Neither mechanism prevents people from leaving the field empty; enforcement requires a workflow validator (e.g., making the field required on transition), which is a separate configuration step. And if your taxonomy genuinely needs multiple categories per issue, use a multi-select field instead of forcing single-select, accepting slightly messier gadget grouping.