Skip to main content

Quay.io Webhook Receiver

The Quay.io webhook receiver responds to "Push to Repository" events originating from Quay.io repositories by "refreshing" all Warehouse resources subscribed to those repositories.

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.

Configuring the Receiver​

A Quay.io webhook receiver must reference a Kubernetes Secret resource with a secret key in its data map.

info

This secret will not be shared directly with Quay.io.

Quay.io does not natively implement any mechanism whereby receivers may authenticate inbound webhook requests. To compensate for this, Kargo incorporates the secret into the generation of a hard-to-guess URL for the receiver. This URL serves as a de facto shared secret and authentication mechanism.

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: q-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: q-wh-receiver
      quay:
        secretRef:
          name: q-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 Quay.io​

To configure a single Quay.io repository to notify a receiver when objects (like container images or Helm charts) have been pushed to it:

  1. Navigate to https://quay.io/repository/<account>/<repository>?tab=settings, where <account> has been replaced with a Quay.io 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.

    Repository Settings

  2. In the Events and Notifications section, click Create Notification.

  3. Complete the Create repository notification form.

    Create Repository Notification Form

    1. In the When this event occurs dropdown, select Push to Repository.

    2. In the Then issue a notification dropdown, select Webhook POST.

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

    4. Click Create Notification.

    Created

info

Verifying delivery of webhook requests can be difficult as Quay.io offers a mechanism for submitting test webhook requests, but offers no way to view the results of such a request.

info

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