Skip to main content

The GitHub Webhook Receiver

The Github Webhook Receiver will respond to ping, push, and package events originating from GitHub repositories.

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

In response to a push event, the receiver "refreshes" Warehouses subscribed to the Git repository from which the event originated.

In response to a package event, the receiver "refreshes" Warehouses subscribed to the GHCR repository from which the event 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.

Configuring the Receiver​

The GitHub webhook receiver will need to reference a Kubernetes Secret with a secret key in its data map. This shared secret will be used by GitHub to sign requests. The receiver will use it to authenticate those requests by verifying their signatures.

note

The following command is suggested for generating a complex shared secret:

openssl rand -base64 48 | tr -d '=+/' | head -c 32
apiVersion: v1
kind: Secret
metadata:
  name: gh-wh-secret
  namespace: kargo-demo
stringData:
  secret: <your-secret-here>
---
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 configuration. We can obtain this URL using the following command:

  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, we will present instructions for both options.

Webhooks from a Single Repository​

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

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

    Settings

  2. Click Add webhook.

  3. Complete the Add webhook form:

    Add Webhook Form

    1. Set Payload URL to the URL retrieved for the webhook receiver.

    2. Set Content type to application/json.

    3. Set Secret to the value assigned to the secret key of the Secret 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 checked.

      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 remains checked.

    6. Click Add webhook.

  4. Verify connectivity:

    1. From the Webhooks dashboard, select the webhook you registered above.

      Webhooks

    2. Select the Recent Deliveries tab.

      Recent Deliveries

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

      Ping Response

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/<org name>/settings/apps, where <org name> 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:

    Register New GitHub App Form

    1. Set Github App name to a name of your choosing.

      note

      This name must be globally unique across all of GitHub.

      Unfortunately, you will not learn whether your selected name is unavailable until you have submitted the form.

    2. Set Homepage URL to a URL of your choosing. The value of this field is unimportant.

    3. Skip the Identifying and authorizing users and Post installation sections of the form. These are not relevant to our present goal.

    4. Set Webhook URL to the URL retrieved for the webhook receiver.

    5. Set Secret to the value assigned to the secret key of the Secret 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 checked.

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

      note

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

      Subscribe to Events

    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.

      Ping Response

  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 to 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.