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.

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.

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