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.

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.

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

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.

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.

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.

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.

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.

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

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.

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.

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.

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 support@zenhub.com 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.