GitHub project management: a guide

Using Zenhub to enhance GitHub’s project management capabilities, including:

  • Creating scaleable task hierarchies in GitHub.
  • Enhancing productivity with Ai and automation.
  • Integrating agile practices seamlessly into GitHub.
  • Enhancing project visibility for stakeholders using customizable roadmaps and agile reports that are powered by live GitHub data.

15-minute read

Team-based software development happens in GitHub, so it’s only natural to want to manage projects closely with or inside the platform. At some point, most software teams have asked themselves the same question: How can they better plan, track, and prioritize their work without leaving GitHub?

Within its UI, GitHub provides basic project management capabilities that give teams some structure to sort Issues in the form of project boards and simple Gantt charts. However, teams quickly find that GitHub’s project management capabilities are limited and require project organization by repository. This makes it impossible to coordinate a team of teams, requiring that everyone have the same level of GitHub access which can put your source code at risk of being shared or compromised.  Not to mention the challenges communicating project vision and granting visibility to collaborators who don’t have GitHub accounts (like execs, the product team, etc.).

To fill in these gaps, software teams use Zenhub to enhance GitHub’s task hierarchy and organization, as well as implement ai-powered, automated agile processes and greater project visibility, performance tracking, and more.

In this guide, we will cover:

  • The relationship between Zenhub and GitHub
  • How to set up Zenhub for the first time
  • How to use Zenhub for day-to-day software project management
  • How to use Zenhub for enhanced project visibility
  • Where to learn more about and enhance your Zenhub skills

The Zenhub difference: Understanding Zenhub and its unique relationship with GitHub

Zenhub brings enhanced agility to Agile development, directly in GitHub. It supports Agile principles and methodologies but gives you complete freedom to apply them in the best way for your team. In this section, we explain:

  • Zenhub terminology and how it relates to Agile and GitHub terms
  • The Zenhub information hierarchy and what it means in terms of your work in GitHub
  • How Zenhub takes you beyond GitHub Projects without adding complexity or constraints

Or click here to skip to “Setting up Zenhub for the first time.”

Agile terminology vs. Zenhub and GitHub terms

In general, Zenhub and GitHub speak the same language and use the same terms in the same way, so there’s no big shift to a new vocabulary when you start using Zenhub.

*This is not a native GitHub feature. If you are using Zenhub, you can access these inside of GitHub using Zenhub’s browser extension.

Zenhub has a seamless and secure relationship with GitHub

Zenhub can provide this level of integration and flexibility because it has full read and write access to your GitHub repositories. Our encryption and access control policies protect your data at all times, and our entire security framework—infrastructure, development practices, management processes, and incident response capabilities—is certified to Security and Organizations Controls 2 (SOC 2) standards.

Learn more about access and permissions here.

What's the difference between GitHub Projects and Zenhub?

GitHub projects is a basic, simple project management tool that works best for teams smaller than 5. Conversely, Zenhub enables scalable project management in GitHub that empowers both GitHub and non-GitHub users to collaborate more efficiently on software projects with Ai suggestions and automations, enhanced visibility, performance insights, and more.

Here are some of the key enhancements Zenhub makes to GitHub projects:

Enhanced org-wide collaboration

Cross-collaborate with non-developer teammates

In Zenhub, “Zenhub Issues” capture work that isn’t happening in GitHub so non-technical team members can plan work alongside developers. This is a great way to bring product people, designers, execs, etc., to the table without needing to grant them GitHub access. When in Zenhub, they’ll be able to view both Zenhub and GitHub Issues on the project board, giving them complete visibility into engineering work and the opportunity to plan their work alongside it.

Zenhub vs. GitHub Issues – suggested use cases:

  • Use GitHub Issues to capture work that will be done solely by a developer with a GitHub account, such as bug tracking.
  • Use Zenhub Issues to capture work that requires cross-functional collaboration or visibility.

Because Zenhub and GitHub are so tightly integrated, issues already created in GitHub are available in Zenhub as soon as you link your Zenhub account with GitHub account and add repositories to your Zenhub Workspace.

Note: You can create and manage both GitHub Issues and Zenhub Issues in Zenhub and by using the Zenhub browser extension in GitHub.

Connect multiple repositories to a single board with Workspaces

Unlike in GitHub projects where each repository is treated as a project you have to manually add issues to, in Zenhub, you can connect multiple repositories to a single Kanban board (even those from different organizations) and customize which Issues appear in which board. Once you set your preferences, Zenhub automatically populates boards with them and organizes pipelines based on issue status.

Connect multiple teams boards with workflow automation

Workflow automation enables the automatic triggering of an issue’s movement from one board to another board’s pipeline based on the issue’s status. This this ideal for teams that frequently work cross-collaboratively but want to maintain separate boards.

See why SwaggerAPI switched from GitHub Projects to Zenhub

“It [Zenhub] gave us the capability to have a single workflow with minimal overhead and integration with different GitHub contexts, not to mention much better reporting and planning features than were available elsewhere."

Francesco Tumanischvili
Lead Developer

Read their story

Enhanced project visibility and performance insight

Instant performance analytics with GitHub Insights

Zenhub’s GitHub Insights feature gives high-level views and deeper insights into your team’s performance, including:

  • Software engineering performance metrics based on your team’s historical GitHub data
  • The ability to benchmark your team’s performance against the top 100 GitHub repositories
  • Get actionable, tailored recommendations on processes improvements for better results

Org-wide and team-level visibility with real-time roadmaps

  • Organize Projects and Epics in a timeline view. Add Projects and Epics from other Workspaces for greater org-wide visibility.
  • See which projects are on track and which are at risk of missing deadlines at a glance with real-time progress predictions based on your team’s calculated velocity. As developers close out Issues this prediction will recalculate so you’re always informed.

Built-in agile processes for GitHub

Automated sprints for faster planning and backlog refinement

In Zenhub, you can set up automated, recurring sprints based on your team's preferences. Zenhub will build your sprint plans based on your team velocity so that just the right amount of work is planned. Enable Zenhub to automatically carry over incomplete issues and issues to the next sprint, if desired.

Planning poker for issue estimates

Using planning poker to estimate issue effort is a well-known concept in Agile development. However, Zenhub planning poker includes key features that set it apart:

  • Planning poker is built into Zenhub. There’s no need to use a separate tool or GitHub add-on.
  • Voting happens asychronously, meaning team members can vote on issue effort simultaneously or on their own time. This is ideal for teams working remotely or in different time zones.
  • Zenhub notifies users when its time to provide estimates.

Why use Zenhub planning poker?

Get non-biased feedback – voting happens anonymously, ensuring everyone has an equal, unbiased say.

Spend less time in meetings – Zenhub planning poker allows you to rule out the issues your team already has alignment on so you only need to meet to discuss those your team is not in agreement on.

Agile reports

Zenhub provides a number of Agile reports that make it easy to view and share progress with anyone in the company:

  • Burndown reports let you see how much work your team has completed and how much work is left to complete in the sprint.
  • Velocity tracking reports let you see how many story points were completed in past sprints so you can track your software team’s velocity over time.
  • Release reports let you forecast delivery dates, manage scope changes, and catch bottlenecks in projects early.
  • Cumulative flow reports let you see how work flows across your board to understand workload, throughput, and issue progress.
  • Control Chart reports let you see how long issues take from start to finish.

The Zenhub project information hierarchy

Here’s a look at the hierarchy and relationships between the main Zenhub elements and their connection to information in GitHub where there is one.

Milestones and Sprints

Sprints: A group of Issues that your team has committed to complete and release by the end of the sprint, which typically lasts between 2-4 weeks. In Agile project management, sprints are meant to render small, functional releases rather than one large feature (which would take longer to complete than 2-4 weeks).

Milestone: A shorter term marker that reflects the completion of a particular group of GitHub Issues. A GitHub milestone can reflect a key completion point in a release, or it can be used to track time-boxed efforts where limited, or no, scope changes are expected.

To Sprint or Milestone? Generally, we recommend using Sprints as it follows best practices for agile project management and can be set up automatically in Zenhub. Zenhub’s milestone feature is primarily meant to support teams already using GitHub Milestones who don’t wish to move to sprints.

Setting up Zenhub for the first time

In this section, we outline the basic steps to get Zenhub up and running with GitHub for the first time. We cover:

  • The GitHub permissions you need before you start
  • Logging in Zenhub and connecting your GitHub account
  • Creating a Zenhub Workspace and adding GitHub repositories
  • Inviting teammates to join your Workspace
  • Setting up sprints and sprint automation
  • Creating GitHub and Zenhub Issues and adding them to sprints

Putting the right GitHub permissions in place

To start managing GitHub projects in Zenhub, you’ll need to give Zenhub the right permissions. The permissions that are associated with the GitHub repositories you work with also apply to Zenhub.

Here’s how GitHub and Zenhub permissions map to one another.

In general, write permissions are needed in Zenhub to:

  • Create sprints and Epics
  • Assign issues
  • Make changes to issues someone else opened
  • Add issues to a release, sprint, or Epic
  • Start a planning poker session and estimate on issues
  • Make changes to the Zenhub board
  • Define or change workflows
  • Add GitHub repositories to a Workspace
Tips for setting up permissions:
  • Only users with Admin-level access can connect their GitHub organization to Zenhub (otherwise Zenhub will just connect your personal account)

  • GitHub Issues must be enabled for all repositories you want to access from Zenhub. Sometimes issues are disabled if you’re working with a forked repository

Logging in to your Zenhub account

To start your Zenhub free trial, go to zenhub.com and click Try for free in the upper right corner. Once you have a Zenhub account, go to zenhub.com and click Login.

Connecting your GitHub account to Zenhub

Some of the most helpful features in Zenhub—like GitHub Insights and the ability to view and manage GitHub Issues and pull requests—are only available after you connect your GitHub account to Zenhub.

The most straightforward approach is for the GitHub organization owner to create the connection between the two accounts, but it’s not mandatory. For more insight, see the Tips below.

To connect your GitHub account to Zenhub

  • Verify that you’re logged in to both GitHub and Zenhub.
  • In Zenhub, click on Connect with GitHub.
  • Click Grant.
  • Click Authorize ZenHubIO.
  • In GitHub, go to the Settings for your organization and click Third-party access so Zenhub will be shown as a third-party GitHub app.
  • Click Review, then Grant.
Tips for connecting GitHub and Zenhub accounts
  • Be sure to click Grant before you click Authorize ZenHubIO in Zenhub. Otherwise, Zenhub will only have access to your personal GitHub account, not your organization.
  • Only the owner of the GitHub organization can see the Grant button in Zenhub.
  • If you’re not the owner of the GitHub organization, click Request beside your organization and give the owner a heads up they’ll receive an automated email from GitHub.


Remember:
The Zenhub team will never touch your code or read your pull requests, and we apply advanced security measures, including full Advanced Encryption Standard (AES) 256-bit encryption, to keep your code and information safe.

Get Zenhub free

Getting started with Workspaces

A Zenhub Workspace enables teams to collaborate with work in one place where they can organize and plan projects, track performance, and plan sprints. Workspaces are connected to one or more GitHub repositories so you can view and track GitHub Issues and pull requests end-to-end, along with your Zenhub Issues.

What’s in a Zenhub Workspace?

Workspaces include:

  • A Kanban board
  • Agile performance reports (these reflect the work that was done by the team that’s working in a Workspace)
  • A unique roadmap (you can add Epics from other Workspaces to your roadmap if desired)
  • The ability to plan sprints (this only happens at the Workspace level)

In Workspaces, you can:

  • Add any number of private or public GitHub repositories (you can also filter these by Issue labels if you don’t wish to add all issues from a single repo).
  • Create multiple Workspaces and then connect them through Workflow Automation, so individual teams can work on the same set of issues, using their own custom board setup.
  • Import your GitHub Projects board into your Zenhub Workspace.

To get started, in the upper left corner of Zenhub, click Create new Workspace.

All of the GitHub Issues in the selected repositories are automatically sorted into the default pipelines on the Zenhub board based on their current status. As we describe in the next section, you can easily customize pipelines and move issues between pipelines to better fit the way your team works.

Inviting teammates to join your Workspace

Development is a team sport, so you’ll want to invite your teammates to join your Zenhub Workspace to start assigning issues and Epics, create team sprints, track team productivity, and engage in planning poker sessions. To get started, in the bottom left corner of Zenhub, click Invite your team.

Who should be in a Workspace?

Workspaces work best when everyone in the space has similar goals, a similar workflow, and/or they or their managers would like their performance tracked together. Remember – a Zenhub user can be involved in multiple Workspaces, so don’t feel the need to fit everyone into one. In general, we find 3-7 people per space is ideal, and no more than 10 active workers in a board to avoid crowding it.

Some common use cases teams have for creating new Workspace are:

  • To create a single space for bug tracking.
  • To create a space for teams that have a unique workflow like DevOps, or non-technical teams like Customer Service or Product.
  • A unique roadmap (you can add Epics from other Workspaces to your roadmap if desired)
  • To create a space for initiatives that require more cross-functional collaboration.

Creating projects, Epics, and releases

We’ve already defined each of these Zenhub elements, so we'll get straight to how to plan new projects and epics in your workspace.

To create a new project

  • In the sidebar, click Roadmap.
  • Beside Projects and Epics, click + and select New project.
  • Enter a title for the project and click Save.
  • In the Projects and Epics list, select your new project, then click on the three vertical dots and select Set start and end date.

Use the calendar to identify the project timeline, then click Set timeline.

To create an Epic and add it to a project

  • In the sidebar, click Epics. The Epics tag will give you complete views of all of your current and former Epics.
  • From here, select New Epic.
  • Enter a title, description, and timeline for the Epic. You can also select a “Project” to associate that Epic with. Remember to click Save.
  • To add Issues to your Epic, select the Epic and click “New GitHub Issue.” To add Zenhub Issues select the “+.”

To create a new release (a group of Epics and Issues), in the sidebar, select “+” then Create → Release.

Tip for managing projects

To add a project description, mark the project as complete, or to edit the project, click on the project name in the Projects and Epics list.

Creating milestones

GitHub milestones are supported for consistency with GitHub, and for use with GitHub Issues.

To get started, in the sidebar, select Create → Milestone.

Setting up sprints and sprint automation

Zenhub sprints function in a similar way to GitHub milestones, but provide added benefits, and are an ideal way to track the velocity of short-term iterations of work that comprises either or both GitHub Issues and Zenhub Issues.

Sprints have the added benefit of automation. When you first set up a sprint you can choose whether Zenhub automatically:

  • Moves unfinished issues to the next sprint
  • Builds new sprints from the issue backlog

When you start with Zenhub, we’ve included 3 pre-set sprints, but you can edit them to fit your team’s cadence by selecting “+” → “Modify recurring sprints” in the sidebar.

Tips for setting up sprints

  • When you select the start and end dates for your current sprint, Zenhub automatically creates two future sprints with the same duration.
  • Issues can live in multiple sprints—a past sprint and a current sprint, for example—but past sprints cannot be reopened.

Creating GitHub and Zenhub Issues and adding them to sprints

You can create GitHub Issues and Zenhub Issues from within Zenhub. Of course, you can also create GitHub Issues in GitHub and they’ll automatically be displayed on your Zenhub board in real-time if your accounts are connected.

To create a GitHub issue, in the sidebar, select “+” → “GitHub Issue.”

To create a Zenhub issue, in the sidebar, select “+” → “Zenhub Issue.”

The two types of issues have almost identical parameters, but GitHub Issues can have a milestone associated with them in addition to a sprint.

Remember:

  • GitHub issues are the best choice for work that will be done solely by a developer with a GitHub account.
  • Zenhub issues are the best choice for work that requires cross-team collaboration or awareness.
  • Labels for GitHub issues are created and managed in GitHub. However, they can be applied to GitHub issues and Zenhub issues in Zenhub. You can also create new labels for Zenhub issues in Zenhub.
Tip for applying the same setting to multiple issues

To apply the same pipeline, assignee, label, sprint, milestone, Epic, release, or estimate to multiple issues, press the shift key when selecting issue cards then click the appropriate Set button at the top of the Zenhub board.

Get Zenhub free

Using Zenhub to simplify your day-to-day work life

In this section, we outline how you can use Zenhub to make day-to-day project management fast, flexible, and easy. We cover:

  • Using pipelines to set up workflows and manage issues
  • Automating issue workflow to synchronize the state of an issue in multiple Workspaces
  • Defining and tracking issue dependencies
  • Using planning poker to create and vote on issue estimates
  • Viewing and managing GitHub Notifications in Zenhub
  • Changing sprint timelines, Workflow Automation, and issue settings

Using pipelines to set up workflows and manage issues

The Zenhub board provides default pipelines that meet the requirements of many Agile teams, but they’re really just a starting point. Below, we’ll tell you how to rename, reorder, add, and remove pipelines to fit your team and workflow.

The ability to customize pipelines is particularly helpful when different teams within your organization have their own Workspace and board. For example, you can create a unique set of pipelines for the dev team, the QA team, and the documentation team, each of which will have a different workflow. The same issues can exist across all the boards, with triggers that synchronize their movements across each group’s unique set of pipelines. We’ll tell you how to set up the automation later in this section.

The default Zenhub pipelines are pretty self-explanatory, but we want to provide more insight into these three:

  • Icebox: Work you don’t expect to work on within the next six months. The Icebox helps give the team clarity on low-priority issues that aren’t worth closing, but also aren’t part of upcoming plans. It also helps ensure that deprioritized issues aren’t reopened.
  • Product backlog: Work that’s ready to go into an upcoming sprint but hasn’t been added to a sprint yet. Keeping the issues in this pipeline prioritized helps teams choose the most important issue to work on if all the issues in the sprint are completed ahead of time.
  • Sprint backlog: Work that’s been committed to and accepted into the upcoming sprint. Keeping the issues in this pipeline prioritized reminds teams which work you’ve committed to doing first in the sprint (e.g. bugs and blockers, etc).

Automating Issue workflows to synchronize the movement of an issue across multiple Workspaces

Zenhub’s Workflow Automation feature lets collaborating teams could easily hand off work when working on the same issues in different Workspaces.

Say a developer moves an Issue from the In Progress pipeline to the Ready for QA pipeline on the Development board. That action can trigger movement of the same issue from the To be Triaged pipeline to the Backlog pipeline on the QA board. The issue being moved on the Dev board is called the trigger pipeline and the corresponding move on the QA board is called the destination pipeline. This makes it easy for the QA team to see when work is ready to be picked up, and saves the developer the hassle of providing a status update through other communication channels.

You can configure Workflow Automation across multiple related Workspaces. For example, moving an Issue to the next stage in the Design Workspace could trigger corresponding Issue movements in the Engineering, Management, Support, and QA Workspaces.

To synchronize workflow between Zenhub boards:

  • In the sidebar, select Workflows.
  • In the current Workspace, select the trigger pipeline.
  • In the related Workspace, select the destination pipeline.
  • Click Connect.
Tips for automating issue workflow
  • By default, Workflow Automation applies to current and future issues in the two pipelines. To move only future issues to the destination pipeline, untick the checkbox at the bottom of the Connect box.
  • Make sure everyone working in the two Workspaces is aware that issues will be automatically moved as their status changes.
  • When the issue is moved to the trigger pipeline, a notification on the board confirms the issue is also being moved to the destination pipeline.
  • You can’t include the Closed pipeline in workflow automation.
  • You can’t automate issue movement between two pipelines in the same workspace.
  • You can’t trigger issue movement into multiple pipelines in the destination workspace.

Defining and tracking Issue dependencies

Issue dependencies let you identify tasks that must be completed before another can begin. The tasks may be within a single team or they may be across teams.

Identifying and tracking Issue dependencies in Zenhub helps teams avoid bottlecks and blockers. It also reduces the risk that dependencies will be missed during team discussions, and group related Issues. In Zenhub, issues can be:

  • Blocked by other issues
  • Blocking other issues

To get started, click on the Issue card to view its parameters. Click on the dependency type to toggle between the two options. You can assign both types of dependency to a single issue.

The following icons identify the issue’s dependencies on its card.

Using planning poker to create and vote on issue estimates

Planning poker in Zenhub is designed to give you the flexibility you need to make it work for your team–whether you’re remote, hybrid, or in-office. The entire team can estimate at the same time, or individuals can submit their estimate at the time that’s most convenient for them—a capability that’s extremely helpful for dispersed teams, especially if they work in different time zones.

You can request estimates:

  • From individual team members
  • From a group of team members
Tips for automating issue workflow
  • By default, Workflow Automation applies to current and future issues in the two pipelines. To move only future issues to the destination pipeline, untick the checkbox at the bottom of the Connect box.
  • Make sure everyone working in the two Workspaces is aware that issues will be automatically moved as their status changes.
  • When the issue is moved to the trigger pipeline, a notification on the board confirms the issue is also being moved to the destination pipeline.
  • You can’t include the Closed pipeline in workflow automation.
  • You can’t automate issue movement between two pipelines in the same workspace.
  • You can’t trigger issue movement into multiple pipelines in the destination workspace.

To request an issue estimate, click on the issue card then, under Estimate, click Add members to vote on estimates.

To help save time, Zenhub remembers the last three groups of members you asked to vote on issues so you can easily request estimates from that same group in the future. These groups are provided at the top of the planning poker participants list.

To request estimates for multiple issues, press Shift as you select the issue cards then click Set estimate in Zenhub’s upper right corner.

Tips for starting a planning poker session

You won’t see the planning poker option below the Estimate field if:

  • The issue already has an estimate and planning poker participants were not added before the estimate was entered.
  • The issue is closed and planning poker participants were not added before the estimate was entered.
  • The issue is for a GitHub pull request.

Viewing and managing GitHub Notifications in Zenhub
Before you can see GitHub Notifications in Zenhub, you need to configure the following in your Notifications settings in GitHub:

  • Set Watching to Web.
  • Set Participating to Web.

To specify which GitHub notifications you want to see in Zenhub, in the sidebar, select Notifications.

Tip for viewing GitHub Notifications

To see the Notifications for another workspace, click the arrows beside the workspace name in the upper left of the Notifications area.

Using Zenhub to see the big picture

Zenhub helps you get visibility into and track your team's progress in real-time while improving long-term planning and performance:

  • Use agile Reports, such as the burndown chart, to see your team’s real-time progress on the current sprint and assess longer term performance.
  • Use the Roadmap to improve long-term planning.

Using Agile reports to get valuable insights

To see the Agile reports available, in the sidebar, select Reports. Here’s how to choose the right report for your needs.

Using the roadmap to help with long-term planning

The Zenhub Roadmap is specific to the Workspace its correlated with. It provides a timeline view of projects and Epics in that Workspace, so you can accurately track project progress and share project status with all stakeholders with no need for meetings.

As the team closes issues and merges pull requests, the roadmap automatically reflects the completed work so you can view the progress of individual projects at a glance.

You can also see an organization-wide Roadmap by clicking on your organization name in the top right corner next to your Workspace name.To get started, in the sidebar, select Roadmap.

Tips for using agile Reports
  • To improve sprint planning accuracy, consider the short-term information in the Burndown report as well as the historical view provided in the Velocity tracking report.
  • Use the Share drop-down list within the report to copy the link to the report or export it to CSV format.

Remember:

To get the most value out of Roadmaps, we recommend you:

  • Add projects and Epics to the roadmap with start and end dates
  • Ensure you have estimates on all issues in the Epics
  • Adjust your roadmap settings for how you’d like your completed work to be displayed, color coding, and views

This is just the beginning

There are so many ways to make managing projects in GitHub more seamless using Zenhub. While this is the end of the guide, there are plenty of other resources that will help you on your Zenhub journey. Be sure to check them out and let a Zenhub team member know if you have any questions!

Get in touch and join our community

You can always email [email protected] with your questions or book an onboarding session to have an expert walk you through the platform. And you can join the Zenhub Community to hear from, interact with, and learn from other Zenhub users.

Make the most of our resources

We’re sharing new content on project management and how to build more productive software teams—whether they develop software for internal use or for external customers.

We conduct surveys and create reports based on the results, publish e-books, blogs, and white papers, and we produce podcasts that explore the stories and strategies behind innovative software startups.

Check out our resources.

Get Zenhub free
Resources

Related content