Webhook pooling
Gearset uses a "webhook pooling" mechanism. For this, the general rule is that for each repo, Gearset needs one webhook to run all CI jobs.
Once a valid webhook event has occurred, Gearset will figure out what CI job to run by:
Looking at which CI jobs are “attached” to that URL (For example, 3 jobs).
Looking at what type of event it is (push), and which branch is affected (e.g.
testQA).Check for CI jobs with the matching source repo and source branch.
When creating a new CI job you will notice that the Payload URL and the shared secret are the same, this is expected behavior.
How many Gearset webhooks should I have in my repo?
As mentioned above, Gearset needs one webhook to run all CI jobs. If you have a pipeline then another webhook will be needed as well.
Bringing the total number of needed webhooks to 2.
Notes:
Azure DevOps uses service hooks instead of webhooks and therefore uses 3 service hooks for the CI jobs and 3 for the pipeline (6 in total). Instructions for manual setup of the service hooks can be found here.
AWS Code Commit users:
For all CI jobs you will need:
1 SNS Topic and Subscription
1 Trigger
For the Pipeline you will need:
1 SNS Topic and Subscription
1 Eventbridge Rule
1 Trigger
Webhook errors
Pipelines is reliant on Webhooks to run as expected. Therefore, if users are wanting to view any errors they are able to click the view webhook errors button and use that to help with the troubleshooting.
Further information on checking your webhooks may be found here
Why do I have many different webhooks in my repo?
Since this is a newer feature, older CI jobs are still running off the 1 to 1 matching webhooks. These will continue to work as expected.
Setting up your webhooks
We recommend letting Gearset set up your webhooks automatically when creating a Pipeline or a CI Job.
For a new Pipeline, this modal will appear during the creation:
We recommend selecting the Add webhook button to automatically create your Pipeline webhook.
If this is not able to be created automatically, select the Manually set up a webhook option, which will then display the required steps to set the webhook up in your chosen git provider as each one is different.
When setting up a CI Job, Gearset will automatically set up the webhook for you where possible. You should see a pop up similar too the below if this is successful:
If this is not successful, select the Webhook setup... option from your CI Job here:
The modal will then guide you through how to setup the webhook in the git provider selected for that CI Job.
Rotating Webhook Secrets
You can rotate the secret for both your CI Job and Pipeline webhooks directly in Gearset.
Rotating a Pipeline webhook secret:
Go to your Pipeline settings cog, and then click Edit webhook, as shown below:
Rotating a CI Job Pool webhook secret:
Rotating the secret:
After opening the modal, you should now see a "Rotate secret" button, where you can trigger the rotation, as shown below:
Gearset will automatically rotate the secret and re-create the webhook for you. If you have sufficient permissions in your VCS, no further action is needed. If you don't, Gearset will still rotate the secret, but you'll need to delete and re-create the webhooks manually in your VCS - follow the same steps as the initial webhook setup above.
For CI Jobs, it's important to note that rotating the secret will impact upon all CI Jobs that are within the same CI Job Pool, given they share a secret (as explained above).