GitHub Webhook Receiver

The GitHub webhook receiver responds to ping, push, and package events originating from GitHub.

The receiver unconditionally responds to ping events with an HTTP 200 status code.

The receiver responds to push events by refreshing all Warehouse resources subscribed to the Git repositories from which those events originated.

The receiver responds to package events by refreshing all Warehouse resources subscribed to the GHCR repositories from which those events originated.

info

"Refreshing" a Warehouse resource means enqueuing it for immediate reconciliation by the Kargo controller, which will execute the discovery of new artifacts from all repositories to which that Warehouse subscribes.

info

The GitHub webhook receiver also works with GitHub Enterprise Cloud and GitHub Enterprise Server, although some URLs in this document may need to be adjusted accordingly.

Configuring the Receiver

A GitHub webhook receiver must reference a Kubernetes Secret resource with a secret key in its data map. This shared secret will be used by GitHub to sign requests and by the receiver to verify those signatures.

note

The following commands are suggested for generating and base64-encoding a complex secret:

secret=$(openssl rand -base64 48 | tr -d '=+/' | head -c 32)
echo "Secret: $secret"
echo "Encoded secret: $(echo -n $secret | base64)"

apiVersion: v1
kind: Secret
metadata:
  name: gh-wh-secret
  namespace: kargo-demo
data:
  secret: <base64-encoded secret>
---
apiVersion: kargo.akuity.io/v1alpha1
kind: ProjectConfig
metadata:
  name: kargo-demo
  namespace: kargo-demo
spec:
  webhookReceivers: 
    - name: gh-wh-receiver
      github:
        secretRef:
          name: gh-wh-secret

Retrieving the Receiver's URL

Kargo will generate a hard-to-guess URL from the receiver's configuration. This URL can be obtained using a command such as the following:

kubectl get projectconfigs kargo-demo \
  -n kargo-demo \
  -o=jsonpath='{.status.webhookReceivers}'

Registering with GitHub

There are two options whereby GitHub repositories can be configured to send events to the webhook receiver:

1. Configure webhooks directly for a single repository.

   The advantage of this approach is that it is comparatively simple, however, its large disadvantage is that it is tedious and most likely infeasible to repeat this configuration for a large number of repositories.

2. Create a GitHub App.

   The disadvantage of this approach is that it is comparatively complex, however, its large advantage is that once created and configured, the App can be easily installed into any number of GitHub repositories (belonging to the same account that owns the App).

In the sections below, you will find instructions for both options.

Webhooks from a Single Repository

To configure a single GitHub repository to notify a receiver of relevant events:

1. Navigate to https://github.com/<account>/<repository>/settings/hooks, where <account> has been replaced with a GitHub username or organization name and <repository> has been replaced with the name of a repository belonging to that account and for which you are an administrator.

   

2. Click Add webhook.

3. Complete the Add webhook form:

   

   1. Complete the Payload URL field using the URL for the webhook receiver.

   2. Set Content type to application/json.

   3. Complete the Secret field using to the (unencoded) value assigned to the secret key of the Secret resource referenced by the webhook receiver's configuration.

   4. Under Which events would you like to trigger this webhook?:

      Leave Just the push event. selected, unless you would like to receive events when container images or Helm charts are pushed to associated GHCR repositories.

      To receive such events, select Let me select individual events., then ensure Pushes and Packages are both selected.

      note

      You will only receive events from those GHCR repositories explicitly associated with your Git repository.

      For more information on this topic, refer to these GitHub docs.

   5. Ensure Active is selected.

   6. Click Add webhook.

4. Verify connectivity:

   1. From the Webhooks dashboard, select the new webhook.

      

   2. Select the Recent Deliveries tab.

      

   3. Select the ping event and ensure an HTTP response status of 200 was received from the webhook receiver.

      

When these steps are complete, the repository will send events to the webhook receiver.

info

For additional information on configuring webhooks, refer directly to the GitHub Docs.

Webhooks from a GitHub App

To configure a GitHub App to notify the receiver of relevant events from any repository into which it's been installed:

1. Navigate to https://github.com/settings/apps to create a new GitHub App owned by your own account

   OR

   Navigate to https://github.com/organizations/<organization>/settings/apps, where <organization> has been replaced with an organization for which you are an administrator to create a new GitHub App owned by that organization.

2. Complete the Register new GitHub App form:

   

   1. Complete the GitHub App name field using a name of your choosing.

      note

      This name must be globally unique across all of GitHub.

      Unfortunately, you will not learn whether the name you've selected is available or not until you have submitted the form.

   2. Complete the Homepage URL field using a URL of your choosing.

      info

      This is a required field, but for our purposes, its value is unimportant.

   3. Skip the Identifying and authorizing users and Post installation sections of the form.

      info

      These sections are not relevant to webhook delivery.

   4. Complete the Webhook URL field using the URL for the webhook receiver.

   5. Complete the Secret field using the (unencoded) value assigned to the secret key of the Secret resource referenced by the webhook receiver's configuration.

   6. In the Permissions section of the form, expand Repository Permissions.

   7. Ensure Contents is set to Read-only.

   8. If you would like to receive events when container images or Helm charts are pushed to associated GHCR repositories, set Packages to Read-only.

      note

      You will only receive events from those GHCR repositories explicitly associated with your Git repository.

      For more information on this topic, refer to these GitHub docs.

   9. In the Subscribe to events section of the form, ensure Push is selected.

      If you would like to receive events when container images or Helm charts are pushed to associated GHCR repositories, ensure Packages is also selected.

      note

      The events available for selection in this section of the form are dynamic and dependent on your selections in the Permissions section.

      

   10. Under Where can this GitHub App be installed? ensure Only this account is selected.

       danger

       If you select the other option (Any account), your App will be installable into any repository in GitHub, regardless of what account owns it. Every repository into which your App is installed will send events to the webhook receiver. You almost certainly do not want this!

   11. Click Create GitHub App.

3. Verify connectivity:

   1. From the new App's settings page, select Advanced from the left sidebar.

   2. Under Recent Deliveries, select the ping event and ensure an HTTP response status of 200 was received from the webhook receiver.

      

4. Install the new GitHub App into one or more repositories:

   1. Select Install App from the left sidebar.

      You will be presented with a list of accounts (users or organizations) into which you may install the App. If you followed the instructions for creating the App as presented above, only the account owning the App should be listed here.

   2. Click Install next to the account into which you wish to install the App.

      An installation dialog will appear.

   3. Under for these repositories, select:

      • All repositories if you wish for all repositories owned by the account to send events to the webhook receiver.

        note

        Selecting this option will result in the App also being installed in new repositories belonging to the account as they are created.

      • Only select repositories if you wish for only specific, existing repositories owned by the account to send events to the webhook receiver.

        note

        If this option is selected, the installation process can be repeated in the future to install the App into additional repositories.

   4. Click Install.

When these steps are complete, all repositories into which your GitHub App has been installed will send events to the webhook receiver.

info

For additional information on configuring webhooks for GitHub Apps, refer directly to the GitHub Docs.