Epics in GitHub: how to create them 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 useful ways of categorizing software development tasks, also known as “Issues.” If you’ve been using GitHub for project management, you may have noticed that GitHub’s project management suite isn’t as built out as others on the market. More specifically, GitHub lacks the ability to create project task hierarchies and run Agile processes. Because of this, “Epics” is not a concept native to GitHub.

Unless you’re using Zenhub. Zenhub is an Agile project management tool that seamlessly integrates with GitHub via an extension (it can also be accessed on its own). This enables teams to do things like create more detailed project hierarchies, manage multi-repository projects, build roadmaps, and run Agile processes effortlessly with AI and automation.

Zenhub Epics is a way to group your Issues into a larger group of work that all aim to complete the same goal. This keeps your tasks better organized, and the team focused on one goal per Epic.

First, what is an Epic?

An Epic in Agile and project management is a large body of work that can be broken down into smaller tasks or issues. It’s essentially a container for tasks that are related to a specific theme or goal, allowing for better organization and tracking of complex projects. Epics help teams manage and visualize the progress of significant features or components over time, ensuring that all related tasks are aligned toward the completion of the overarching goal.

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 adds 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 that contain several sub-tasks needed to complete the larger goal.

How to create Epics in GitHub

Before you can create Epics in GitHub, you’re going to need to sign up for Zenhub and download the Zenhub extension for GitHub (Note: you can also create Epics and manage projects with or without GitHub at app.Zenhub.com).

Once you’ve got the extension up and running and you’re logged in, navigate over to the “Zenhub” section of GitHub. This is in between “Pull Requests” and “Actions.” This section acts as a complete project management suite inside of GitHub, where you can manage your GitHub Issues in Zenhub.

1. Create a new Epic

From the “Epics” section of the left-hand navigation, click “New Epic.” From here, add a description, title, and expected timeline for Epic. Then select “Create Epic” to lock that in.

Once you’ve got your Epic created, you can select the search button to search for already existing GitHub Issues to start adding 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 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 explaining 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:

FAQs on Working with Epics inside GitHub with Zenhub

What are Epics in Zenhub?

Epics in Zenhub group related GitHub issues into larger units of work for better project and release planning.

How do I create an Epic in Zenhub?

Create an Epic in Zenhub by selecting “New Epic” and linking relevant GitHub issues to it.

Can I convert a GitHub issue into an Epic?

Yes, you can convert existing GitHub issues into epics in Zenhub to organize and track projects efficiently.

How does Zenhub enhance Agile project management?

In addition to traditional Agile tools like Kanban boards, Zenhub includes a suite of AI and automated Agile tools like automated sprint planning, AI-generated acceptance criteria, AI sprint reviews, and automated asynchronous Planning Poker. Zenhub also includes real-time product roadmaps and Agile reports like burndown charts (referred to as “Sprint Reports” in Zenhub), control charts, release reports and more.

Get in touch!

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