The best part about working in ZenHub is that you never need to leave GitHub to manage workflows. To set up ZenHub's integration with GitHub, you'll need to authenticate your ZenHub account and organization – here's how. We promise it's not as complicated as it looks.
What you'll need
- Github username
- Github password
- The owner of the organization you are trying to authenticate with ZenHub
Authenticating ZenHub in GitHub
Click on the "Start my free trial" button below. Once you're in, click "Sign up using GitHub," which will redirect you to GitHub. From here, sign in to your Github account.
If you are the owner of the GitHub organization, you should see a "Grant" button beside your organization. We know it's tempting, but DO NOT push the big green button until you have pressed "Grant." Otherwise, ZenHub will not have access to your organization, only your personal GitHub account.
If you are not the owner, you will need to click the "Request" button beside your organization.
Note: Once members hit "Request," GitHub will send the owner an automated email.
Although they are completely safe and legitimate, GitHub's automated permission emails look a little… fishy…, so here's an example of what it looks like so the owner is aware:
We recommend giving your organization owner a heads up to expect this email before hitting "Request."
Once you've selected "Grant" or "Request," you can go ahead and push the big green "Authenticate ZenHubIO" button. If you are the organization owner, no further action is needed– welcome to ZenHub!
If you're a member, now's the time to hand the baton over to the organization owner–they'll need to follow the instructions in Step 4.
Your organization owner will need to go into the GitHub organization settings and click "Third Party Access."
ZenHub should appear as a third-party GitHub app. Click "Review" and then "Grant." Once access is granted, it should say "Approved." That's it. That wasn't so hard, was it? We're glad you're in– welcome!
I noticed that third-party GitHub apps allow access to my GitHub ID, and I do not want my personal GitHub items accessible in my work account. How do I separate them?
If you are concerned about your work account having access to your personal GitHub information, there are two ways to solve this:
Way #1: Create a separate business account using your work email address for business purposes.
Way #2: Create a separate GitHub organization for personal data and move your data over into that organization.
For more information on privacy at ZenHub, go to www.zenhub.com/privacy.
I am seeing an error that I do not have permissions. What's going on?
In this case, you likely have not granted ZenHub access yet. To enable ZenHub in GitHub, every organization you wish to connect with ZenHub must receive third-party permissions.
To confirm an access blockage due to permission restrictions, go to your GitHub profile settings and head to Applications > Authorized OAuth apps. If you see ZenHub listed with a red X beside it, that indicates that third-party restrictions are enabled. Click "Review" and then "Grant Access" to enable permissions.
If you see a green checkmark and are still having trouble, it may be a caching issue. If ZenHub has been granted access in the last 3 hours, force ZenHub to check for new permissions by either refreshing the web app or revoking your token in the OAuth apps section and then reauthenticating by clicking "Sign in."
I accidentally pushed "Authenticate ZenHubIO" without granting permission. How do I grant ZenHub permissions?
If you're the organization owner, you will need to sign up with ZenHub again and be sure to hit the "Grant" button before pressing "Authenticate ZenHubIO." If you are an organization member, you will need the owner to grant permission.
For more information on GitHub authentication, visit our Help Center