Skip to main content

How to Create a Component Hierarchy in Jira

· 5 min read
NGPilot

Jira components were designed for a flat world: one list, no nesting, no structure. That works at ten components and collapses at fifty — when "SSO" sits next to "Platform" and "Mobile" with nothing expressing that it belongs under "Auth", which belongs under "Platform". Teams end up encoding the architecture in name prefixes and maintaining ever-growing component in (...) lists by hand. This guide covers three ways to get a component hierarchy in Jira, and what each one costs.

Quick answer: Jira cannot nest components natively. Component Hierarchy for Jira adds a parent-child tree per project: build it on a project page, pick a full path like Platform/Auth/SSO on each issue with a cascading picker, and search whole branches with one JQL function — inComponentHierarchy("Auth") — instead of maintained component lists. Every node is a real Jira component, so boards, releases, and reports keep working.

Why a Flat Component List Stops Working​

The flat model fails in a specific, predictable way: the structure lives in people's heads, and every tool that needs it re-asks for it. A board filter wants the list of platform components. A report wants everything under Auth. A new subcomponent invalidates every one of those lists at once. Multiply by a few areas and a few teams, and "which components make up the platform?" becomes tribal knowledge with a shelf life.

Method 1 — Naming Conventions (Free, Fragile)​

Rename components into paths: platform-auth-sso, platform-auth-oauth, mobile-auth-sso. Sorting by name fakes a tree view, and the prefix tells humans where things belong.

Good for: small projects that need a visible grouping and nothing more.

What's missing: the hierarchy is in the string, and nothing queries it. There is no JQL for "everything starting with platform-auth- and everything under it" — you still enumerate members. Conventions also rot: one person types Platform-auth, another creates platform-auth-sso-v2, and every filter built on the prefix quietly misses issues. Structure by convention needs a curator, and curators move on.

Method 2 — Labels or a Custom Field (Searchable, Unstructured)​

Give issues a second axis: a label like area-auth or a single-select custom field "Subsystem". JQL can now filter on it.

Good for: one level of grouping that only needs to answer "all issues in area X".

What's missing: a flat field cannot answer path questions — "everything under Platform, at any depth" becomes another explicit list of values. There is no cascade (pick Auth and SSO must follow), no structure for a service catalog, and now you maintain two parallel truths: the components boards use, and the field reports use. They drift.

Method 3 — a Real Component Tree (Recommended)​

Component Hierarchy for Jira adds the missing dimension on top of components, not instead of them:

  1. Build the tree on the project page (project sidebar → Apps → Component Hierarchy): add root nodes, nest children as deep as needed, move subtrees, rename anything. Changes save automatically, and every node is a real Jira component — existing components with matching names are adopted, never duplicated.

  2. Pick a path on each issue. The Component Hierarchy field is a cascading picker — level by level from roots to leaves — available on issues, create dialogs, transition screens, and JSM portal requests. Setting it adds the selected nodes' components to the issue automatically (it only ever adds).

  3. Search branches with one clause. inComponentHierarchy("Auth") returns every issue whose path is Auth or starts with Auth/, at any depth:

    inComponentHierarchy("Auth") AND status != Done
    inComponentHierarchy("Platform") AND assignee = currentUser()
    not inComponentHierarchy("Deprecated")

    Two nodes sharing a name at different depths? Add the level: inComponentHierarchy("Auth", 2).

Because queries resolve through the tree, they stay correct as it evolves: rename a node and every issue shows the new name immediately; add a subcomponent tomorrow and every saved filter covering its parent already covers it. No more lists to maintain.

Bulk-Build the Tree from CSV​

For a project with an established component list, don't click the tree into existence — import it:

Name,Parent
Platform,
Auth,Platform
SSO,Auth
OAuth,Auth
Mobile,

A blank Parent marks a root; every parent must be defined in its own row. Download the exact template from the project page, fill it in, and import — the import replaces the current tree (export first if you want a backup), and the Sync components button creates a Jira component for any node still missing one.

Which Method Should You Use?​

NeedUse
A visible grouping on a handful of componentsNaming conventions
One flat "subsystem" axis for filteringLabel or single-select field
A real tree: cascading picker, subtree JQL, service catalogsComponent Hierarchy for Jira

The third row is the one that survives growth: the tree stays the single source of structure, components stay the single source of truth for boards and reports, and branch queries cost one function call instead of a maintained list. Install Component Hierarchy for Jira, import your existing structure as CSV, and let inComponentHierarchy() replace the lists.

Related guides