ZenHub and GitHub Permission Structure
"How do ZenHub and GitHub permissions work?" A question we come across a lot! 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.
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.
GitHub Permissions and what actions you can perform in ZenHub
For a quick reference guide on what GitHub permissions are needed for key ZenHub functionality, see below:
Making changes to Issues
|Open new Issues||✖||✖|
|Close or re-open Issues||✖ (You can only close/re-open Issues you create)||✖ (To make changes to any 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 and milestones to Issues||✖|
Making changes to the ZenHub Board
|Invite someone to your ZenHub Board||✖ (Link sharing only)||✖|
|Move Issues on the ZenHub board (between, or within pipelines)||✖|
|View the ZenHub Board||✖||✖|
Making changes in GitHub/ZenHub
|Adding Issues to a Release or Milestone||✖|
|Assigning an Issue to an Epic||✖|
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:
|Action||Does this impact just you, or is it a global team change?||Permissions needed|
|Adding, renaming, or deleting a pipeline||Global: 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 Board||Just 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 Milestones||Global: This change is managed in GitHub and will be global for anyone accessing that repo.||Write|
|Creating Release Reports||Global: 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|
|Toggling off a Milestone in the Velocity Chart||Just for you: When viewing the Velocity chart, you can 'toggle off' a Milestone to re-calculate the average. When turning off a Milestone from view, this is only for your own view.||Write|
|Filtering the Board||Just 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 pipeline||Global: Any Issue movement changes will be updated for anyone who has repo access.||Write|
|Creating new Estimates/deleting existing ones||Global: 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 Issue||Global: 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.
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.