How to create epics in GitHub using ZenHub

Editor’s note: This blog post was originally published in April 2016 and has been completely revamped and updated for accuracy and comprehensiveness.

“Epics” are one of the most powerful tools for planning and executing on software releases. But they’re too often paired with clunky, bloated, decidedly non-agile tools.

ZenHub Epics make it easy to execute on product backlogs, providing a crucial “extra layer” of hierarchy to your GitHub issues.

Previously, GitHub users either had to jump into a third-party tool (a major distraction from the code) , or use laborious workarounds , to do what an epic accomplishes. With ZenHub, teams can now create epics directly from their existing GitHub issues, then get back to work.

Using Epics in GitHub for more project clarity

Before adding ZenHub, your GitHub issues have no real hierarchy; they’re simply a list. But which issues are related? Where do the dependencies lie? It’s difficult to say.

ZenHub Epics add a crucial extra layer of hierarchy to your GitHub issues, providing greater control end-to-end over the release process. Simply put, ZenHub Epics are a theme of work which contain several sub-tasks needed to complete the larger goal.

How to create epics in GitHub

1. Add existing GitHub issues to a new epic

When creating a new issue, you’ll notice a purple button: “Create Epic”. It’s a magical portal to the new Epic Builder:

The Epic Builder makes it easy to batch-add issues (displayed as a vertical task board) without jumping back into the main issues tab. Clicking the checkboxes on the right will add issues to your epic.

2. Top it up with new issues

But wait – you’re probably thinking. I don’t have all the issues I need for this epic — how organized do you think I am?!

We hear you — that’s where the Quick Issue Creator comes in. Add a title, then click “New Issue” to have it appear at the top of your list. (You can just go back later to add more detail.)

Next add a description of that epic’s theme: a few lines communicating why these issues are grouped. Finally, click “Create Epic”!

Turning a GitHub issue into an Epic with ZenHub

We’ve all been there: you started writing an issue, and halfway through, it’s starting to read more like a novel. But how do you know if you should turn your issue into an epic?

Firstly, each issue should take the smallest possible amount of time. If you estimate your issue will take weeks or months to finish, it should probably become an epic.

Similarly, if your issue is too complex — if several sub-tasks are required to mark it as “done” — it’s better off as an epic. By splitting each task into easily-completed chunks of work, you’ll reduce technical debt and be able to ship impactful changes more frequently.

Use the Epics drop-down on the right to convert an issue into an epic. (The issue’s existing text will display as a comment). You can also use this drop-down menu to add an issue directly into an existing epic:

Tracking agile project progress and visualizing Epics

The most impactful part of epics isn’t creating them — it’s tracking them in an effective way.

We recommend creating two new pipelines to helps organize Epics. Epics aren’t meant to move throughout your Board, but be the vessel to help you track user stories and key projects in a central location.

Having a designated pipeline for Epics, as well as Epic Priorities helps the team understand what is a continuous project, versus one that is actively moving forward. We recommend using the Priority Epic pipeline for work that is actively moving forward within the next 3 months.

With ZenHub Boards, you can view how epics fit into the big picture by seeing them alongside your other issues. By the same token, you can Filter by Epic to see only the issues inside it.

Get in touch!

As always, we welcome your feedback! Chat with us anytime on Twitter or email us at support@zenhub.com.