# 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. > Give Jira components a parent-child tree: platforms, modules, submodules — cascading issue picker, subtree-wide JQL search, and reports that keep working. ## 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 - **[Component Hierarchy for Jira](/apps/component-hierarchy-for-jira.md)** — Turn flat Jira components into a parent-child tree and search any branch with a single JQL function · [Install from Atlassian Marketplace](https://marketplace.atlassian.com/apps/2232005585?utm_source=ngpilot.com&utm_medium=website&utm_campaign=scenario-component-hierarchy-in-jira) ## Read the guides - [How to Create a Component Hierarchy in Jira](/blog/jira-component-hierarchy.md) ## Frequently asked questions ### Can Jira components have a parent-child hierarchy? 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. ### How do I search all issues under a component and its subcomponents? Use the inComponentHierarchy("Auth") JQL function — it returns every issue whose path is Auth or starts with Auth/, at any depth. If two nodes share a name at different depths, add the level as a second argument: inComponentHierarchy("Auth", 2). ### Will a component tree break my boards and reports? No. Tree nodes are real Jira components — setting the path field on an issue adds those components to it automatically — so every board, dashboard, and report that filters by component continues to work unchanged. The hierarchy adds structure; it does not migrate anything. ### How do I create a component hierarchy for an existing project? List the existing components, decide the nesting, and import the tree as a CSV with Name,Parent rows — nodes matching existing component names are adopted rather than duplicated. A sync action creates components for any node still missing one. ### What happens to issue values when a node is renamed or moved? Issues resolve their path from the tree at display time, so a rename shows up immediately on every affected issue, and JQL results recalculate automatically — values are linked to the node, not frozen as text the day they were picked. ## Ready to try it? All NGPILOT apps are free for up to 10 users and install in one click from the Atlassian Marketplace. Browse the [full app catalog](/apps.md) or read more [scenario solutions](/solutions.md).