webhooks.md

Webhooks

Garm is designed to auto-scale github runners. To achieve this, garm relies on GitHub Webhooks. Webhooks allow garm to react to workflow events from your repository, organization or enterprise.

In your repository or organization, navigate to Settings --> Webhooks:

And click on Add webhook.

In the Payload URL field, enter the URL to the garm webhook endpoint. The garm API endpoint for webhooks is:

POST /webhooks

If garm is running on a server under the domain garm.example.com, then that field should be set to https://garm.example.com/webhooks.

In the webhook configuration page under Content type you will need to select application/json, set the proper webhook URL and, really important, make sure you configure a webhook secret. Garm will authenticate the payloads to make sure they are coming from GitHub.

The webhook secret must be secure. Use something like this to generate one:

gabriel@rossak:~$ function generate_secret () {
    tr -dc 'a-zA-Z0-9!@#$%^&*()_+?><~\`;' < /dev/urandom | head -c 64;
    echo ''
}

gabriel@rossak:~$ generate_secret
9Q<fVm5dtRhUIJ>*nsr*S54g0imK64(!2$Ns6C!~VsH(p)cFj+AMLug%LM!R%FOQ

Make a note of that secret, as you'll need it later when you define the repo/org/enterprise in GARM.

While you can use http for your webhook, I highly recommend you set up a proper x509 certificate for your GARM server and use https instead. If you choose https, GitHub will present you with an additional option to configure the SSL certificate verification.

If you're testing and want to use a self signed certificate, you can disable SSL verification or just use http, but for production you should use https with a proper certificate and SSL verification set to enabled.

It's fairly trivial to set up a proper x509 certificate for your GARM server. You can use Let's Encrypt to get a free certificate.

Next, you can choose which events GitHub should send to garm via webhooks. Click on Let me select individual events.

Now select Workflow jobs (should be at the bottom). You can send everything if you want, but any events garm doesn't care about will simply be ignored.

Finally, click on Add webhook and you're done.

GitHub will send a test webhook to your endpoint. If all is well, you should see a green checkmark next to your webhook.