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
Zenhub offers flexible login options, including Google SSO and email with a password. To fully unlock Zenhub's capabilities, a GitHub Organization connection is required. Once your GitHub Organization is connected to Zenhub, you can utilize GitHub SSO for seamless access.
This integration aligns Zenhub's features with your GitHub repositories' access permissions, ensuring that visibility within Zenhub reflects your GitHub permissions. Without this connection, you will not be able to view or manage GitHub issues 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 Permissions | Zenhub permissions |
| Read | Read |
| Triage | Read |
| Write | Write |
| Maintain | Write |
| Admin | Write |
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
| |||||||||||
| 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:
| 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 sprints | Global: This change will be global for all users in the Workspace | 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 |
| Creating workflow connections | Global: 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 chart | Just 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 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.
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.