Arrow left
Blog Homepage

GitHub for Project Management - How to Organize and Track Your Agile Processes

GitHub for Project Management - How to Organize and Track Your Agile Processes

Editor’s note: This blog post on GitHub project management was originally published in June 2016 and has been completely revamped and updated for accuracy and comprehensiveness.

This article is an excerpt from our book 'Better Software & Stronger Teams'. For the full guide to building a collaborative software team, pick up your free copy!

What Is Agile?

Agile development – or simply Agile –– is an iterative approach to software development that emphasizes flexibility, interactivity, and a high level of transparency.

Agile projects involve the frequent release of useable code (revenue), continuous testing (quality), and acceptance that whatever you think you know now, it’ll change (reality!). With a few tweaks and some basic understanding of agile best practices, you can turn GitHub into a powerful agile platform... and reap the sweet, sweet benefits of the GitHub data your team is constantly creating.

GitHub Is Actually Perfect for Project Management

GitHub reinvented what it means to collaborate on code. They championed a new era of open source development, which naturally transitioned into a profitable business driven from the ground up by developers who love the platform.

If something has code, there’s a good chance it was developed or refined on GitHub. It’s where the world’s top software teams write, collaborate on, and ship amazing products.

The Issue of Focus: How Most Project Management Tools Fail Developers

As GitHub took over the development world, project management companies rushed to integrate with it in an attempt to bridge management and development teams. But every solution shares the same problem.

They all “live” outside GitHub, forcing developers to jump from tool to tool to update tasks, tickets, and reports. We call this context switching, and it’s much more costly than we expect.

People, as a rule, are terrible multitaskers. A study by the Journal of Experimental Psychology found that people who multitask see a 40% drop in productivity. When interrupted from a task, it takes 20-30 minutes to refocus. Switching between low-performance tasks – say, texting a friend while watching TV – isn’t too difficult. Getting back to where you were before (zoning out in front of Netflix) takes nearly no time at all.

But when tasks are complicated, the cost of context switching skyrockets. Consider a developer in the middle of coding a new feature. Here, a five-minute interruption takes much longer than five minutes.

Steve Fenton puts it this way:

“If a developer is interrupted with a question, it could put their work back by hours for each interruption. This is because of the amount of stuff they are holding in their immediate memory while they are working on a feature. They will have parsed lots of code in the area they will be working on and will have projected their changes in their mind before they start coding and the interruption will impact their focus on this information.

Once interrupted the developer may decide to batch other interruptions like email into the break – but this elongates the gap and makes it more likely that the information will be squirreled away into harder to access places.”

How ZenHub Helps

It’s not enough to instruct, hope, or pray engineers stay focused. As software-driven companies, everything – down to the tools we use – should reinforce our commitment to the software first. (This is why we created a tool, ZenHub, which brings the project management process inside GitHub. Not close to, not ”integrated with”, but inside.)

github for project management being connected to ZenHub
Centralizing your team in one system carries other benefits, like:

More Accurate Metrics for GitHub Project Management

  • Third-party tools result in silos of information. By creating a single source of truth, your data is always up to date.

Focus on Product, Not Process

  • Project managers shouldn’t spend their day reminding coworkers to update tickets. When everything is centralized, project managers spend more time managing the project, and less time worrying about the people building it.

Collaboration as a Habit

  • GitHub issues were built for collaboration. Collaboration not only helps reduce error and technical debt, it actually keeps teams happier. In one study, enterprise companies that identified collaboration as the top priority significantly improved employee satisfaction, customer retention, and productivity (Aberdeen Group, 2013).

We surveyed over 500 software engineers, developers, and project managers to find out what happens when a software development team adopts ZenHub.

Who Should Use GitHub for Project Management?

We think anyone invested in the success of a GitHub project can benefit from managing that project closer to the code. These groups see the highest benefit:

Technical Team Leads

You’re the person whose job it is to remove roadblocks from the path of your software team... at any cost. It’s your mission to help engineers be as productive, collaborative, and happy as they possibly can be. Your business card might say project manager, Scrum Master, product lead, or program manager. If you’re at a startup, you might even be the Head of Engineering or CTO.

You’re uniquely capable of empathizing with developers’ needs, probably because you’ve been there yourself, so you’re ultra-committed to managing expectations on all sides and shielding programmers from distraction. You, my friend, are a Technical Team Lead.


You’ve heard all the buzzwords: agile; scrum; planning poker; kanban; product owner. You may or may particularly not care for them. Maybe you’ve been burned in the past.

Doing agile in GitHub isn’t about splitting hairs on Project Management Theory; there are tons of great resources out there if you want them. Applying basic agile concepts to GitHub will help your projects run more smoothly, without additional overhead or process. And you’ll become a better agile team member in the process. (Because whether you realize it or not, you’re probably already part of an agile team!)

More Than Issues: Setting up an Agile Process in GitHub

setting up an Agile process in GitHub

Like a message board for your ideas, issues are GitHub’s task tracking system, used to log bugs and scope out new features. Issues provide a place to talk about the amazing software you’re building.

But in their current state – organized in a list – it’s difficult to glean important information about Issues in a glance. You can’t easily understand their progress or priority.

ZenHub’s extension adds a crucial layer of prioritization and planning to GitHub issues.

Ready for GitHub project management?

Mapping Agile Concepts into GitHub

Sprint → Milestone

In Scrum, sprints are a fixed length of time during which an agreed-upon chunk of work is completed and ready to be shipped. Sprints, or “iterations”, are mirrored in GitHub with Milestones. Simply set a start and end date (typically two or four weeks), and add user stories to begin sprinting.

setting milestones in GitHub

Note: Teams should decide together how much work they commit to tackling every Milestone. Things get easier when you have some historical data to back up your assumptions. ZenHub offers the ability to attach story point estimates to GitHub issues, then visualize their progress in customized reports.

User Stories → GitHub Issues

User stories are high-level feature descriptions that help define benefit from a customer’s perspective. They’re often written in this format, which is intended to keep things simple and focused on business value: As a <user type>, I want <a goal> so that <benefit>.

turning user stories into GitHub issues

If you’re adhering to this structure, make it your issue’s title. You can also set up GitHub issue templates to add detail or acceptance criteria when the time comes.

Epics → Epics

No need to map this concept: ZenHub provides epics inside GitHub. Epics help teams plan and collaborate on product backlogs; they’re essentially just big user stories (for example, "Dashboard Redesign" would be an Epic, while "Change CTA colour" would be an issue within that Epic). Using ZenHub, you can map out big chunk of work using Epics, then add related issues to flesh it out.

Epics have flexible scope, so you can add, edit, and remove issues as needed. Once you’ve set up an epic, you can track it alongside your other work in ZenHub Boards. Or, filter by epic to track only those issues.

Note: In contrast to Milestones, Epics are not necessarily related by time. It can take several Milestones to complete an Epic, and that’s OK!

using ZenHub to create epics directly in GitHub

Product backlog → Open issues without a Milestone

Your product backlog, sometimes referred to as a Master Story List, includes, well – pretty much everything. Typically ordered vertically by each issue’s business value, ours is a collection of user stories, half-baked feature ideas, things we might do in the future, technical work, and anything else. The point is to make a habit of getting stuff out of your head, and into GitHub.

Be honest with yourself, though: if it’s never going to get done, it’s best to close the issue.

customer success Kanban board in GitHub

Sprint backlog → Issues with a Milestone

Your sprint backlog contains the work your team has committed to tackling in a given Milestone. Your team can collaborate to add Estimates to issues (by time or complexity), requirements, and attach a Milestone. We suggest ordering issues vertically by priority on your ZenHub Board.

To groom things even further, use the Icebox pipeline to “freeze” stories that aren’t a priority, and the Backlog pipeline to prioritize issues for multiple Milestones. When a team member is ready for a new task, they simply filter the Board by Milestone, then drag issues from the Backlog to In Progress pipelines.

icebox and product backlog on a Kanban board

Note: Beware of scope creep. Once a sprint begins, your issues should remain fixed.

Pssst! If you haven't already, download ZenHub free to get task boards, epics, and more – directly added to GitHub.

P.S. If you found this guide to GitHub project management useful (and would like others like it), let us know by passing it along to a friend. :)

Describes how to use ZenHub with your GitHub data to see all your teams, projects, and priorities in one place.

Project Management
Newsletter Icon