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

ZenHub and GitHub Permission Structure

Within ZenHub, user permissions and access vary based on the permissions a user has within GitHub. Here is a summary of GitHub and ZenHub permissions.

Get to know how ZenHub leverages the GitHub permission model to provide access. Currently ZenHub authenticates at the user level, leveraging GitHub OAuth authentication to provide user-level access for ZenHub to all the organizations (and repos within that organization) that the user has access to, where there aren't third-party application restrictions in place. 

Accessing ZenHub

The credentials that you use to log in to GitHub are the credentials you will use to access ZenHub. Similarly, the access permissions you have associated with your user account for your GitHub repositories will carry through to ZenHub. Meaning, if you don't have access to a repository in GitHub, you will not be able to see any issues or information about that repository in ZenHub

GitHubs repository level permissions in ZenHub. 

GitHub offers five different permission levels for members with access to a repository. Within ZenHub, GitHub permissions translate to either read or write access for users. For a quick reference on how GitHub permissions translate in ZenHub, see below:

GitHub PermissionsZenHub permissions

Note: ZenHub updates its permissions cache about once every 3 hours. If you have just recently been granted Write access to a repository and are still seeing it as Read-Only in ZenHub, you may need to wait up to 3 hours to see the change.

GitHub Issues must be enabled

GitHub Issues must be enabled for all repositories you wish to use ZenHub with. Check Settings > General > Features to determine if Issues have been turned off for your repo. This can happen when you are working with a forked repository.

GitHub Permissions and what actions you can perform in ZenHub 

You can learn more about GitHub's repository-level permissions (such as Read and Write) here. 

For a quick reference guide on what GitHub permissions are needed for key ZenHub functionality, see below:

Making changes to issues

Read Permissions
Triage Permissions
Write Permissions
Maintain PermissionsAdmin Permissions
Open new issues
Close or re-open issues(You can only close/re-open issues you create) (You can only close/re-open issues you create)(To make changes to any issues)(To make changes to any issues)(To make changes to any issues)
Assign issues
(Note: Users on the GitHub Free plan are limited to one assignee for issues)

(Note: Users on the GitHub Free plan are limited to one assignee for issues)
(Note: Users on the GitHub Free plan are limited to one assignee for issues)
Have an issue assigned to you

Edit and delete your own comments on issues
Edit and delete anyone's comments on issues
Apply labels to issues
Making changes to the ZenHub Board

Add repositories to a Workspace
Invite someone to your ZenHub Board(Link sharing only)(Link sharing only)
Move issues on the ZenHub board (between, or within pipelines)
View the ZenHub Board
Creating epics
Starting a planning poker session/voting on issues
Estimating issues

Creating/ editing Workflows
Making changes in GitHub/ZenHub

Creating sprints

Adding issues to a release or sprint
Assigning an issue to an epic

We do not currently support GitHubs 'Triage' permission level

We not support GitHubs 'Triage' permission level. In order to manage issues and perform actions such as moving issues between pipelines, assigning estimates to issues and applying labels to issues, then users will need to have write permissions for the repos.

ZenHub vs. GitHub Admin Permissions

Becoming a ZenHub admin is different than being an admin for a GitHub repository—this is important to remember when deciding who on your team you want to administer your ZenHub account! 

ZenHub admin privileges are designed to make it easy for a small group of users in the product to allocate licenses for the team, manage payments and payment information, as well as keep your billing information updated. The ZenHub admin does not need admin privileges to the repo or org, but you do need to ensure you are part of your team's organization, and have permissions to at least 1 repository to be a ZenHub admin.

Global and user-level changes in ZenHub and permissions needed

Actions that you perform in ZenHub can either impact just you, or they can be global changes that impact your whole team. Below is a list of the user and global changes that can be done, and what permissions you need to perform them:

ActionDoes this impact just you, or is it a global team change?Permissions needed
Adding, renaming, or deleting a pipelineGlobal: Doing any of these actions will be a global change for anyone using the Board where you are making this change.Write
Adding a repo to a Board view (Creating multi-repo Boards), or disconnecting an existing multi-repo Board.Global: Any connections and disconnections made are made for everyone in the team who have write permissions. If someone doesn't have permissions to the repo you're adding, they won't be able to see this connection.Write
Editing labels (Renaming, deleting, or creating new ones)Global: This change is managed in GitHub and will be global for anyone accessing that repo.Write
Collapsing/Expanding pipelines on the BoardJust for you: This is a view-option customization. Collapsing your own view will not disrupt anyone else in the team.Write
Toggling off metadata on the issue cards (I.e. Turning off showing labels on issue cards via board view options).Just for you: This is a view-option customization. Hiding/showing metadata on the issue cards will be saved for just you. This will be updated in your browser URL so you can share the view with others.Write
Creating sprintsGlobal: This change will be global for all users in the WorkspaceWrite
Creating release reportsGlobal: Creating new releases will mean that release is available for anyone with Read permissions to filter by, and anyone with Write permissions to edit.Write
Creating workflow connectionsGlobal: Any workflow connections made are global. This will trigger pipeline automation for all team members working in the Workspace.Write
Toggling off a sprint in the velocity chartJust for you: When viewing the velocity chart, you can 'toggle off' a sprint to re-calculate the average. When turning off a sprint from view, this is only for your own view.Write
Filtering the BoardJust for you: Changing your filters, or sorting pipelines only impacts what you see.Read or Write
Moving issues between pipelines, or, up/down within a pipelineGlobal: Any issue movement changes will be updated for anyone who has repo access.Write
Creating new estimates/deleting existing onesGlobal: Any changes to the estimates dropdown on the issue page is global. If you delete an estimate that you don't use, anyone using that Board will no longer be able to use that estimate.Write
Converting an issue to an epic, or and epic to an issueGlobal: Doing any issue <> epic conversions will be done for anyone using the repo.Write

Common permission/access questions

I have a multi-repo board: Could someone view all the connected repos?

If you have 6 repos connected together, but someone only has access to 3 of them, they won't actually even know that the other 3 are connected! They will only see the repos that they have read or write access to. For example, if your team prefers to work out of a single repository, but the source code repos are connected for the sake of viewing everything in one place (as well being able to link issues and Pull Requests together), only the developers with source code repo access will see that work, your team will only see the movement of the issues.

Can I grant access to the ZenHub board and reports, without also giving them access to the associated repos?

With read permissions, someone would be able to view the code/fork the repo if you'd like them to access the boards and burndown for that repo.

Teams in the past have used a workflow where they have an issues-only repo that's merged with the code repo, where only those that have access to both repos see the code and the issues. Whereas those with just access to the issues-only repo don't see the code but get access to the Boards and Reports.

I was just given Write access but I can't move issues in our Workspace!

ZenHub caches permissions for up to 3 hours, which means you may need to clear your browser cache (cookies and other site data) in order to start using your new permissions right away.

My organization isn’t appearing in the web app, but I'm a member of an organization's repository!

If you’re a contributor to a repository, but not a member of the organization in GitHub, the repositories will be listed under Private repos I have access to when first logging in, or through the sidebar navigation. If you still can't access a repo you have access to in the web app, third party restrictions might be enabled and preventing it from appearing. 

Check out our article on troubleshooting this issue for more details! If you’re still having trouble after checking permissions, get in touch with us.

Did you find it helpful? Yes No

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