GitHub Issue Sync
How Zenhub keeps your GitHub issues in sync
Zenhub allows you to add GitHub Issues to your workspace as a data source. Zenhub will then maintain a two-way sync between those issues. This means that any change you make to the issue in Zenhub will be reflected in GitHub, and any change you make to that same issue in GitHub will also be reflected back in Zenhub.
This is achieved through a proprietary data synchronization engine we have developed at Zenhub that ensures both databases (GitHub and Zenhub) have accurate and up-to-date records.
To ensure this process works reliably and quickly, Zenhub will do two things:
Automatically setup a webhook on your GitHub repository which is used to notify the Zenhub system when changes to issues are made on the GitHub side, and
Periodically scan your GitHub repository for any data changes that may not have been reported through the webhooks
How do I setup the necessary webhooks?
You do NOT need to manually create any webhooks. Zenhub will do this for you automatically when a GitHub repository is added to a Zenhub workspace, however, there are a few important conditions to this:
In order for Zenhub to have the ability to automatically create webhooks in GitHub on your behalf, Zenhub needs admin access to the repository. This means at least one GitHub user with admin access to the repository must log into Zenhub. Once this is done, Zenhub will use the tokens from that user to manage the webhooks on your behalf.
GitHub must be able to connect to Zenhub's webhook servers. If you're using an On Premise GitHub Enterprise Server deployment (or some other restricted GitHub Enterprise environment), it's important that the GitHub server is able to connect to Zenhub via the network.
To confirm that both of those conditions are working properly, go the your GitHub repository settings page, click on "Webhooks" in the left-hand menu, and make sure you see a webhook to the Zenhub app created, active and showing recent activity. It will look something like this:
FAQ
Q: I'm seeing outdated titles, descriptions, labels or PR statuses. Why are my GitHub issues not syncing to Zenhub properly?
A: The most common reason this might be happening is because something isn't working with the webhooks that Zenhub created in your GitHub repository. Review the information above under "How do I setup the necessary webhooks?", visit your GitHub repository and double check that you're seeing successful webhook connections.
If you don't see a webhook for *.zenhub.com at all, make sure that a GitHub user that has admin rights to the GitHub repository logs into Zenhub. Once they login and visit your Zenhub workspace (after a short delay), Zenhub will be automatically attempt to re-create the missing webhook.
If you see the webhook, but it has a red icon, click on "Edit" and inspect the latest connection attempts. It's possible GitHub is failing to communicate with the Zenhub servers for some reason. If you're seeing errors here and you're not sure how to resolve them, contact us at support@zenhub.com for help.
If you see the webhook, and it has a green icon -- it's likely there's some other reason why the data isn't syncing properly. It's normal that there is a short 1-10 second delay between when data is updated in GitHub and when it appears in Zenhub, but if you're seeing delays that are much longer than that check to see if GitHub is having an outage or a performance degradation at https://www.githubstatus.com/.
If you've done all of the above, but you're still seeing delays and issues, please contact us at support@zenhub.com for help.
Q: I don't have admin access to the GitHub repository and the other admins aren't Zenhub users. Does this mean the sync will be broken?
If there is nobody in your organization who has the necessary admin access to the GitHub repository, webhooks will NOT be properly setup. This doesn't mean sync will be fully broken, but you should expect significant delays. Zenhub will still periodically perform a manual sync of the issue data, but you should expect long 8+ hours delays.
Being able to setup webhooks is critical to ensuring fast and reliable data syncs between GitHub and Zenhub.