Let’s talk about Jira’s issue hierarchy

[#1]

Image: Charlie from ‘It’s always sunny in Philadelphia' wrangling a complex equation.

For people new to Jira software projects, the issue hierarchy can appear to be a tricky beast to wrangle.

Let’s break it down together. Here’s a bird’s-eye view:

Issue hierarchy showing child issues sitting underneath epics, which sit within the project.

What is an epic?

Let’s forget about child issues for a moment, and answer the first gnarly question: What’s an epic?

Epics are large pieces of work that are complex, and/or span a long period of time. Projects can contain many epics.

In one scenario, you could think of epics as similar to milestones within a project – as you complete each epic, you get closer to achieving the project’s ultimate goal. For example:

Image: Issue hierarchy showing ‘My first app’ project with four epics underneath it: competitor audit, build features, fix all bugs, and prep release.

Or, your project may not have an end goal; it's simply a place to house your team’s ongoing work. In this scenario, epics contribute to the project’s overall purpose, and completing each epic is like completing a smaller project containing multiple tasks:

Image: Issue hierarchy showing ‘Team Pancake’ project with four epics underneath it: website refresh, feature ideation, bug bashing, and a11y (accessibility) focus.

To learn more about epics, check out our tutorial on how to use epics.

After that technical information, here’s a picture of a dog with a pancake on its face:

Image: A dog with a pancake draped over it’s face.

Now let’s get back to the nitty gritty…

What is a child issue?

Epics get broken down into multiple child issues. Child issues are small, discreet pieces of work. Completing each child issue within an epic means you’re getting closer to the epic’s finish line.

Child issues can be different types:

• Story

• Task

• Bug

Read more about issue types, including the differences between each one.

(Here's a juicy nugget of info: if you're on a Premium plan, you can create an additional issue level above epics, called initiatives. In this scenario, epics are child issues of initiatives. Read more about initiatives and epics.)

What about a child issue's child issue?

Yes, you can add another layer beneath child issues, of even smaller pieces of work. These new issues are also called child issues (see diagram below), and their type is subtask.

Image: Issue hierarchy showing all four layers: project, epics, child issues, and additional child issues (subtasks).

A simplified real-world example

Here’s how issues might look if someone built an app in a Jira software project:

Image: Example of an issue hierarchy demonstrating an app’s development.

On the timeline in Jira

Here’s how those issues above would look on the timeline in a software project, with start and end dates added as schedule bars:

Image: The above example’s issues would look like this on the timeline in a Jira software project.

Each child issue under each epic has an icon (circled below) indicating that it has additional child issues within it. Hovering over the icon reveals how many:

Image: The child issue icon is circled, indicating that this child issue has additional child issues.

 If one issue depends on another...

There’s a lot more you can do on the timeline, including adding dependencies between issues. Discover how to use dependencies, or simply explore more about using the timeline.

Seeing something different in your project?

• As mentioned earlier, if you’re using Plans (on Premium), your Jira admin may have added an extra layer of issues above epics. Contact your Jira admin for clarity.

• Can’t see anything called epics? Admins can change the epic name in the issue hierarchy, so epics may be called something entirely different in your project. Contact your Jira admin for clarity.

• Business projects don’t have epics by default (but Jira admins can add them).

• Service projects don’t have epics.

Want to learn more? Check out this in-depth look at Jira’s issue hierarchy.

Hopefully you’re feeling a bit like this now:

Image: Happy dog with flower in mouth.

Got a question? Ask us below!

[Marc Nerenberg]

Let's assume that the hierarchy levels work well. In some cases, however, someone would like to create a task directly under a project in a hierarchy that has been created e.g. Project->Epic->Story->Task, without creating the Epic and Story levels. Would that be possible? And if so, how do you do it?