Organize Jira Components into a Tree
Jira components are a flat list — fine for three entries, unusable at fifty. Learn how to give components a parent-child tree and search whole branches with one JQL clause.
Why this matters in Jira
Jira components were designed for a flat world: one list, no nesting, no structure. That works until the project outgrows a dozen components — then "Auth" sits next to "Platform" and "Mobile" with nothing expressing that SSO belongs to Auth, which belongs to Platform. Teams respond by inventing naming conventions (platform-auth-sso), duplicating components per team, or keeping the real structure in a Confluence page that drifts out of date the week after someone screenshots it.
Flat lists cannot express how systems nest
Real architectures are trees: a platform contains modules, modules contain submodules. A flat component list flattens that knowledge away, so nobody can ask "everything under Platform" without manually listing the members — and re-listing them every time one is added, renamed, or moved. The structure exists in everyone’s heads; it just is not in Jira.
Naming conventions are structure by convention
Prefixes like platform-auth-sso encode hierarchy in strings, which sort() can read but JQL cannot: there is no query for "starts with the platform- prefix and everything under it". Conventions also rot — one typo, one renamed area, and every dashboard filter built on the convention quietly misses issues.
JQL over components does not scale past a handful
The native answer to "all Auth issues" is component in (Auth, SSO, OAuth, Sessions, ...) — a literal list that every new subcomponent invalidates and every board filter, dashboard, and saved filter must duplicate. The list grows with the architecture, and each copy is another place to forget an entry.
Service catalogs and QA need paths, not labels
A support portal that files requests against "Billing" is ambiguous the moment two products both have billing. Paths like Catalog/Billing/Refunds say exactly where an issue belongs, let QA scope test coverage to a subsystem, and give reports a middle ground between "one component" and "the whole project".
The approach that works
A workable component hierarchy comes from four decisions: model the tree around ownership rather than org charts, keep nodes as real components so existing tooling survives, capture the full path on each issue, and make subtree search a single JQL function instead of a maintained list.
- 1
Model the tree around how work is owned
Start from the layers that actually assign work — platform, module, submodule — not from the org chart, which reorganizes. Two or three levels cover most systems; deeper trees usually signal a missing project split. Multiple roots are normal (Platform and Services can sit side by side), and one project is one tree.
- 2
Keep every node a real Jira component
The tree should sit on top of components, not replace them: creating a node creates the component, and existing components are adopted when names match. This is what keeps boards, release notes, permission schemes, and every existing report working — the hierarchy becomes additional structure, never a migration.
- 3
Capture the full path on each issue
Give issues a cascading picker that resolves level by level — Platform, then Auth, then SSO — and stores the whole path. A path is unambiguous where a bare component name is not, and it makes the middle levels queryable: every issue under Platform, regardless of how deep.
- 4
Search branches with one JQL function
Replace component in (...) lists with a single subtree query — inComponentHierarchy("Auth") — that matches a node and everything beneath it at any depth. The saved filters, boards, and dashboards built on it stop needing maintenance: add a subcomponent tomorrow and every query that covers its parent already covers it.
- 5
Bulk-build and keep it in sync
For an established project, define the tree in a spreadsheet and import it as CSV (one Name,Parent row per node) instead of clicking it into existence. Export the tree as JSON for backup, and use a component sync so every node always has its matching Jira component — including after a CSV import.
This solution is for you if…
- Admins of projects whose component list has outgrown a single screen
- Engineering teams encoding architecture in component name prefixes today
- Support leads building service catalogs with unambiguous request categories
- QA scoping test coverage and defect reports to a subsystem rather than a project
- Anyone maintaining component in (...) JQL lists that grow with every release
Our apps that solve this
Every app is free for up to 10 users on the Atlassian Marketplace.
JiraComponent Hierarchy for Jira
Parent-child component trees with subtree-wide JQL search
Read the guides
Frequently asked questions
Not natively — components are a flat list in stock Jira. Component Hierarchy for Jira adds a parent-child tree per project: nodes can nest as deep as needed, and every node remains a real Jira component so boards and reports keep working.
Why teams choose NGPILOT
Free for up to 10 users
Every app is free for small teams, with the full trial Atlassian provides for larger ones.
Native Forge apps
Built on Atlassian Forge, running entirely on Atlassian Cloud infrastructure.
Your data stays in your instance
No content is sent to our servers — processing happens inside your Confluence or Jira.
Verified Marketplace vendor
NGPILOT apps are listed, reviewed, and maintained on the Atlassian Marketplace.
Ready to try it?
Every app is free for up to 10 users. Install in a couple of clicks.