Help Center
Note: Zenhub's full feature set is unlocked when you connect your GitHub Organization to Zenhub

Zenhub helps teams manage projects at scale, enabling multiple teams to collaborate and have ownership over the project planning process. Using GitHub issues and Zenhub epics, you can track tasks, large scale projects, and even small to-do lists.

  • Checklists within issues allow teams to understand how they're progressing on to-do's. 
  • Issues track specifics the team is working on, keeping teams aligned on work in progress.
  • Epics make it possible to organize information and keep track of how GitHub issues roll up into larger projects and initiatives.
  • and projects, as labelled through the use of Epics, help teams determine scope and keep your roadmap on track.

Use epics for themes of work, projects, and goals

It's important to first define whether a piece of work is small enough to be an issue, or needs to scale into an epic. First, consider the time it takes to complete a task and it's complexity: Issues should be completed in the smallest amount of time possible, and be very specific. If an Issue will take weeks or months to finish, has a lot of moving parts, it should probably be an epic, with multiple issues under it.

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. It also helps you follow best practices for how to effectively plan and track Sprints.

Checklists VS. issues VS. epics

There are two ways in GitHub and Zenhub to create 'sub-tasks' or lists of work that need to be done. To help teams better scale projects and keep work organized, below are best practices for using checklists, issues, and epics.

Using markdown, you can create basic checklists:

And when you need to track the process of a bundle of work, for example multiple GitHub issues and pull requests, you can roll these up to an epic:

But when it comes to best practices for scaling projects, it's sometimes hard to understand how to best scale up and organize projects to manage work across the Board. We've shared a few tips below.

Questions to help determine when to use a checklist, issue, or epic:

  • Checklists Is this a to-do list, testing plan, or basic check before you consider something 'done'? If yes, use a checklist and keep things simple.
  • IssuesIs what I am working on dependent on something else, or, have work that is dependent on this? If yes, use issues to create the individual work items and be sure to use dependencies to indicate any blockers.
  • Issues/epicsAre the items I want to track going to be individually worked on, or picked up by multiple people? If yes, separate each piece of work in multiple issues and bundle them together using epics
  • Issues/epicsIs what I'm working on going to span multiple sprints? If yes, create each individual piece of work as issues and bundle together using an epic.
  • EpicsAm I using an Issue with a checklist to track a long-term, or large project? Use an epic instead! Separate each checklist item into it's on issue, rolling all Issues into an epic. This will help you clearly estimate work, have clear Issues, and help the team work in small chunks of work.

In addition to the questions above, here's an easy framework for defining whether something should be a checklist, issue, or epic:

  • Use checklists when: you need to keep things simple, and have a list of final to-do's and checks before moving something forward.
  • Use issues when: you want to track the piece of work across your Board (this piece of work will go through multiple phases, be accepted into the Sprint, and can be assigned to anyone).

  • Use epics when: you have large scopes of work, multiple moving parts, and need to see at a glance how complex something is.

If an Issue has multiple elements ie. a backend piece of work is blocking the front-end, that's a sign that your Issue should be broken down further, and not just bundled in a checklist.

A note on issues, checklists, and epics in sprints

When you create an epic, the epic itself shouldn't be 'work' but rather, the container that keeps the project or bundle of similar Issues together. Each individual issue should be what ends up in your sprints, and shuffled on your Board. 

Only accept issues and smaller pieces of work into the sprint. Epics should not be estimated, but instead help teams understand large scope projects. When accepting work into the sprint, be sure to breakdown epics into smaller issues that can be estimated and discussed. More on effective Sprint management here.

To manage epics and projects on your Board, create two new epic pipelines

Having a designated pipeline for epics, as well as epic priorities helps the team understand what is a key priority versus one that is upcoming, or, something that is continuous and ongoing (for example, using an epic to bundle UX improvements). 

We recommend using the priority epic pipeline for work that is actively being worked within the next 3 months. 

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.