Learn how to structure, manage, and track Epics (and other high-level bodies of work) using Zenhub's issue hierarchy and sub-issues


What is an Epic?

An Epic is a high-level issue type used to group related tasks and organize work around a larger goal. In Zenhub, Epics are parent issues that contain sub-issues representing individual work items that a team would complete during a Sprint. This hierarchy helps teams break down complex efforts into manageable pieces while maintaining visibility of broader objectives.


Epics often span multiple sprints and are ideal for planning features, cross-functional initiatives, or user-facing deliverables that require coordinated effort.


Epics often roll up into larger bodies of work. The default hierarchy that Zenhub provides is:


Initiative → Project → Epic → Task/Feature/Bug → Sub-task


High-level Issues (Initiatives, Projects,  Epics) can be found in the Goals & Planning Panel and Timeline. Lower-level Issues (Tasks, Features, Bugs, Sub-tasks) can be found on the Work Tracker / Board.

Creating an Epic

To create an Epic in Zenhub:

  1. Click the blue + button in the top-left corner of your Goals & Planning Panel

  2. Select Epic

  3. Fill in the title and description.

  4. Click Create Issue to save.



[NOTE]: You can switch between creating a Zenhub Issue-based Epic, or a GitHub Issue-based Epic by clicking the icon next to the word "Create"



Should I use a Zenhub Issue-based Epic or a GitHub Issue-based Epic?

  • If you have GitHub seats for all of your employees, use GitHub issues. 

OR

  • If you have a hybrid organization where some of your team members have GitHub licenses, but others do not, then you should always use Zenhub issue-based Epics. This will allow everyone on the team to be able to collaborate and contribute to breaking your work down.


[NOTE:] Zenhub Issues can be the Parent of Zenhub Issues OR GitHub Issues. GitHub Issues can only be the Parent of other GitHub Issues.


[NOTE]: To create and use Epics, your GitHub and Zenhub organization admins must first configure Issue Types and assign them to the appropriate hierarchy levels. For more details, see the Issue Types setup guide.

[TIP]: Use descriptive titles that communicate the feature or goal the Epic represents. This improves traceability across teams.

Adding Sub-issues to an Epic

Epics use a parent-child relationship with sub-issues. You can add sub-issues in the following ways:

  1. From the Epic issue view
    Open the Epic and go to the Sub-issues section. Click + Add Issue to link existing issues or create new ones directly beneath the Epic.

  2. Using multi-select on the Board
    On your board, hover over issue avatars to select multiple issues. Use the Set Parent action to assign the selected Epic as their parent.

  3. During issue creation
    While creating a new issue, use the Parent Issue field to link it to an Epic.

Sub-issues are typically day-to-day tasks or stories and are categorized at Level 4 of the issue hierarchy.


Tracking Epic Progress

Once sub-issues are linked, you can monitor Epic progress through several views:

  • Board View: Filter by Parent Issue to see only the sub-issues linked to a specific Epic.

  • Timeline View: Visualize scheduling and track how Epics align with other ongoing work.

  • Goals & Planning Panel: See how Epics relate to higher-level items like Projects or Objectives.

  • Sprint Burndown (formerly Sprint Report): Sub-issues roll up into this report to track completion against sprint goals.


[CAUTION]: Only sub-issues (Level 4) are visible in the Sprint Report. Epics provide structure but are not reported on directly.


Filtering for Epics in the Goals & Planning Panel

To view only Epics and monitor their status:

  1. Open the Goals and Planning panel in your Work Tracker.

  2. Click Filters > Issue Type, then select Epic.

  3. Optionally, filter by Status (e.g., Open, Closed top-level, Closed sub-issues) to refine the results.

[NOTE]: Epics will only appear if the Issue Type is set to Epic. Filtering by label alone is not sufficient—be sure the Issue Type is correctly assigned when creating or editing the issue.

FAQ


Q: What is the difference between an Epic and a Project in Zenhub?
A: Projects are broader initiatives (Level 2) and may include multiple Epics (Level 3). Epics represent focused work streams or features within a Project.


Q: Can I convert an existing issue into an Epic?
A: Yes. Open the issue, click the Issue Type selector, and choose Epic. Ensure your admin has configured this Issue Type at Level 3.


Q: Where can I see how Epics and sub-issues relate?
A: Use the Timeline View or Goals & Planning Panel to visualize the hierarchy and understand how Epics align with larger objectives and day-to-day tasks.