Gearset needs two webhooks in your GitHub repository: one to run your CI jobs and one for your Pipeline. Gearset normally creates both when you set up a Pipeline or CI job.
Use this article to create the GitHub webhooks yourself when Gearset can’t or you decide not to.
Note: Only users with the Admin role on a GitHub repository can create webhooks for it. If you don’t have Admin, send the payload URL and secret from Gearset to someone on your team who does.
How many GitHub webhooks does Gearset need?
Gearset needs one GitHub webhook for all CI jobs on a repository and one for the Pipeline, so a repository with one Pipeline has two Gearset webhooks. One webhook covers every CI job because Gearset pools them. When an event arrives, Gearset checks the event type, repository, and branch to decide which CI job to run.
The following table shows how to tell the two Gearset webhooks apart in GitHub by their payload URL.
Webhook | Payload URL contains |
Pipeline webhook |
|
CI job webhook |
|
You set up both webhooks the same way in GitHub. Only the payload URL and secret differ. For more on pooling, see CI job and Pipeline webhooks.
Where do I find the payload URL and secret in Gearset?
Gearset shows the payload URL and secret for each GitHub webhook in a webhook setup modal.
Pipeline webhook: When you create a Pipeline, select
Manually set up a webhookin the webhook step. For an existing Pipeline, click the Pipeline settings cog, then clickEdit webhook.CI job webhook: On the CI jobs page, open the CI job’s menu and select
Webhook setup....
In the modal, expand the manual setup section to see the payload URL and secret.
How do I create a Gearset webhook in GitHub?
Create the Pipeline webhook and the CI job webhook in GitHub with the same steps. You need the Admin role on the repository.
In GitHub, open the repository your Pipeline uses.
Click
Settings, then clickWebhooksin the sidebar.Click
Add webhook. As shown below.
In
Payload URL, paste the payload URL from the Gearset webhook modal.In
Content type, selectapplication/json.In
Secret, paste the secret from the Gearset webhook modal.Under
SSL verification, leaveEnable SSL verificationselected.Under
Which events would you like to trigger this webhook?, selectLet me select individual events. As shown below.
Select
PushesandPull requests.If you’re creating the Pipeline webhook and your Pipeline uses Continuous Delivery Rules, also select
Pull request reviewsandCheck runs.Leave
Activeselected.Click
Add webhook.
Paste the payload URL exactly as Gearset shows it. Gearset also uses application/json when it creates GitHub webhooks automatically, so choose the same content type here.
GitHub adds the webhook to the list on the Webhooks page. Repeat these steps for the second Gearset webhook, using its own payload URL and secret. When you’re done, the Webhooks page lists two Gearset webhooks: one with /pipeline/ in its payload URL and one with /continuous-integration-job/.
How do I check a GitHub webhook is working?
GitHub keeps a log of each webhook’s recent deliveries, so you can confirm Gearset is receiving events. Only repository Admins can see this log.
In GitHub, go to
Settings>Webhooksand clickEditnext to the Gearset webhook.Click
Recent deliveries.Click a delivery to see the request and Gearset’s response.
The response code on each GitHub delivery tells you what happened:
A
2xxresponse, such as202, means Gearset received the delivery.A
401response from the Pipeline webhook means the secret in GitHub doesn’t match the secret in Gearset.A
404response from the CI job webhook can also mean the secret doesn’t match.
To fix a secret mismatch, copy the secret from the Gearset webhook modal again, edit the webhook in GitHub, and paste it into Secret. To resend an event after a fix, open the delivery and click Redeliver.
To check the CI job webhook from the Gearset side, open Webhook setup... on the CI job again. Gearset shows a confirmation when the CI job webhook is set up correctly.
Useful resources
If your Pipeline or CI jobs still don’t run after you set up both webhooks, please send a message to our support team, who will be happy to help.