GitHub
Register a webhook on each GitHub repository with the secret from the repository's flyout, and the branches, commits and pull requests that name your items link themselves and move the items as your project asks; what to tick at GitHub, how deliveries are verified, and what to check when nothing arrives.
By the end of this page a GitHub repository will post its pushes, branches and pull requests to Zuse Bifrost, and the code that names your items will show on them. The connection today is a webhook on each repository, set up once by someone who may change the project's repositories and administer the repository at GitHub.
Before you begin
| To | You need |
|---|---|
| Register the repository | repository:create on the project; see Repositories |
| Set the webhook secret | repository:update on the project |
| Add the webhook at GitHub | Admin rights on the repository at GitHub |
Register the repository
On the project's Code pages, register the repository with its owner and name exactly as GitHub
spells them (zuse-technologies/portal); the webhook names the repository by that full name, and a
mismatch means the deliveries are acknowledged and ignored. The same repository may be registered on
more than one project; each project then links its own items from the same deliveries.
Set the secret
Open the repository's flyout and find Webhook. Set Secret writes a fresh secret, shows it once beside the Address, and keeps it encrypted from then on; copy both before you press Done, because the secret is not shown again. Rotate Secret later replaces it, and deliveries signed with the old one are refused from that moment, so rotate and paste the new one at GitHub in the same sitting.
Add the webhook at GitHub
In the repository's settings at GitHub, under Webhooks, add a webhook:
- Payload URL: the Address from the flyout.
- Content type:
application/json. - Secret: the secret from the flyout.
- Events: Let me select individual events, then tick Pushes, Branch or tag creation, Branch or tag deletion and Pull requests. Nothing else is read.
- Leave Active ticked and save.
GitHub sends a ping at once; the flyout's Webhook line shows when the host was last heard from, so a ping that arrived means the address and the secret are right.
What arrives, and what it does
| GitHub sends | Zuse Bifrost reads |
|---|---|
| A push | The branch pushed to, when its name carries a key, and each commit whose message carries one. |
| A branch created | The branch, when its name carries a key. |
| A branch deleted | A linked branch moves to Closed; an unknown one links nothing. |
| A pull request opened or changed | The pull request, when its title, branch or body carries a key, with its state, author and lines changed. |
| A pull request merged or closed | The pull request's state, and the item's move when the project's switch is on. |
| Anything else | Acknowledged and dropped. |
The links show on the items and on the project's Branches & PRs tab; see Git linking. The moves a pull request makes are on the pull request flow page.
How deliveries are verified
Every delivery is checked before it is read: the signature GitHub puts on the body must match the repository's secret, or the workspace's own GitHub App secret where one is configured; a delivery whose signature matches nothing is refused and never read. A delivery seen before, by its delivery id, is acknowledged and dropped, so a redelivery from GitHub's webhook page changes nothing. A delivery for a repository no project registered is acknowledged and ignored. The reading itself happens off the request, so GitHub always hears back at once and a slow read never shows as a failed delivery at GitHub.
One address, many repositories
Every repository posts to the same address; the body names the repository, and the secret says which registration it may speak for. Set a secret on each repository you register, even when two share an owner.
Frequently asked
GitHub shows the delivery as failed with a 401. The secret at GitHub does not match the one set in the flyout. Rotate the secret in the flyout and paste the new one at GitHub.
GitHub shows 202 and nothing links. Either the repository's full name at GitHub differs from the registration (owner or name misspelled, or renamed since), or the branch, commit or pull request named no key of this project. Fix the registration or put the key in.
Can I use one webhook for a whole organisation? Not yet through the flyout: today the secret is per repository, and an organisation-wide webhook would sign with one secret. The GitHub App that installs across an organisation arrives with a later module; until then, one webhook per repository.
Which GitHub permissions does the webhook need? None beyond admin rights on the repository to add it. Zuse Bifrost reads only what the webhook posts and never calls GitHub back in this slice.
Related
- Git linking: what the links look like on the items and the Branches & PRs tab.
- Pull request flow: the moves a pull request makes.
- Repositories: registering the repository and the webhook section of its flyout.
code.*webhook events: what Zuse Bifrost sends out in turn.
How is this guide?
Last updated on