GitHub Workflows

Achieve More With Epics

Using Epics for GitHub Project Management


Before adding ZenHub, your GitHub issues are organized in a simple list. Which issues are related or dependant? Without ZenHub, it's really hard to say.

ZenHub Epics are, to put it simply, a theme of work that contain sub-tasks required to complete the larger goal. The concept stems from the agile principle that tasks should be broken down into small, manageable chunks; that way, you're able to ship impactful changes more often and ultimately gain more control over the release cycle. In agile development, a “user story” is the smallest unit of work, and an Epic is essentially a “big” user story.

We do this in ZenHub by creating an epic to map out bigger goals, then adding related GitHub issues to flesh it out.

Below, you'll learn how to combine Epics, GitHub issues (user stories), markdown checklists (sub-tasks), and GitHub milestones to ship better software with less overhead.

What's in an Epic?

Three main concepts work together to form an epic. In agile, we know these as Epics, User Stories and Sub-tasks. In GitHub and ZenHub these concepts are reflected as Epics, GitHub issues, and Markdown Checklists.


In this article, you'll learn how these parts come together to form a more powerful GitHub issue management system, helping you plan and execute your product backlog.

But first, a note on GitHub milestones and Epics. While they seem similar at first glance, their purpose is different. In fact, they function best when used together!

In Scrum or agile development, sprints are usually two or four weeks of work, moving toward a goal of shipping business value (features) to the user. In GitHub, milestones are how we plan and execute sprints. So remember, when we talk about GitHub milestones, we're talking about sprints.


Since milestones are tied to sprints, they contain issues related by time, and not necessarily related by subject. The scope of work is fixed once a sprint begins.

In contrast, Epics contain issues related in subject, and the scope is flexible. Issues can be added or removed as teams discover more about the bigger goal.

Epic or GitHub issue?

Not sure whether a GitHub issue should become an epic instead? First, consider the time and complexity: issues should be completed in the smallest amount of time possible. If an issue will take weeks or months to finish, it should probably be an Epic.

Likewise, if an issue is too complicated (if multiple tasks are required to finish it), it's probably better as an Epic. Splitting tasks into easily completed pieces of work will help you ship valuable changes more often and reduce technical debt.

Nested epics and epic lists


Epics in Epics: Nested ZenHub Epics

Plan for multiple projects, add various levels of tasks grouped together, and have everything ordered in the same view as your Board. Epic lists are designed to provide information on where each issue assigned to an epic sits in relation to each other, across your pipelines.

This makes it easy to tackle roadblocks, focus on what's up next, and visualize what other Epics are impacting project progress. When viewing an Epic, if there's a nested Epic, it will default to being collapsed within the list view. Simply click on Show epic issues to view all issues belonging to the nested Epic.

Epic points vs. story points

Epic points are the sum off all estimated story points from the issues that are within the epic points completed status indicator will take the sum of all issues across all nested epics to provide an overview across all projects grouped together. (Learn more about story points and estimates here).

Epic points give a summary of complexity of all issue estimations that belong within a single epic. At the top of the parent epic, the epic points completed indicator will roll-up all estimated issue points across all nested epics/issues.


A workflow for Epics and GitHub milestones

Here's an example workflow that demonstrates how you can pair Epics and GitHub milestones to achieve bigger goals. Let's pretend that we're redoing ZenHub's website.

We'll create an epic for the redesign. Then we'll fill it with GitHub issues: one for each page of the new website.


As we add issues to the Epic, we'll also create checklists of sub-tasks needed to complete each issue. If necessary, we can link out to separate issues for further detail around each sub-task.


Before a sprint begins, we'll create a GitHub milestone to plan our Sprint Backlog. Using estimates and issue priority as a guideline, we'll then decide which issues to add to our milestone. (If we have a refined backlog, this part should be easy.)

We clearly can't complete the entire website in two weeks, but shipping the FAQ page seems doable. We'll add that issue to our milestone, and add a couple bug fixes to flesh out the estimate totals. Together, these issues form a chunk of work that – based on our historical velocity – we believe we could test and ship over the next fourteen days.

As you can see, we end up with three agile layers: epic, issue, and sub-task.

Creating Cross-repo Milestones

If you've created a multi-repo task board, ZenHub makes it easy to create a GitHub Milestone spanning several repositories. This eliminates the need to duplicate work or sync Milestones together.

To get started, find the `+` beside the “New Issue” button on the ZenHub Board.


Here, you'll see a list of all connected repositories from that task board. Remember to set a start and end date here so you can view this Milestone in ZenHub's reports (like Burndown Charts)!

Next Lesson:
I want to estimate GitHub issues
You’ll learn…
  • How to achieve goals consistently via software estimates