GitLab Webhook Receiver

The GitLab Webhook Receiver responds to push events originating from GitLab 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.

info

The GitLab webhook receiver also works with GitLab Dedicated and GitLab Self Managed, although some URLs in this document may need to be adjusted accordingly.

Configuring the Receiver

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

note

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

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

apiVersion: kargo.akuity.io/v1alpha1
kind: Project
metadata:
  name: kargo-demo
---
apiVersion: v1
kind: Secret
metadata:
  name: gl-wh-secret
  namespace: kargo-demo
data:
  secret-token: <base64-encoded secret token>
---
apiVersion: kargo.akuity.io/v1alpha1
kind: ProjectConfig
metadata:
  name: kargo-demo
  namespace: kargo-demo
spec:
  webhookReceivers: 
    - name: gl-wh-receiver
      gitlab:
        secretRef:
          name: gl-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 GitLab

To configure a single GitLab repository to notify a receiver of push events:

1. Navigate to https://gitlab.com/<namespace>/<project>/-/hooks, where <namespace> has been replaced with a GitLab username or group name and <project> has been replaced with the name of a project belonging to that namespace and for which you are an administrator.

   

2. Click Add new webhook.

3. Complete the Webhooks form:

   

   1. Enter a descriptive name in the Name field.

   2. Complete the URL filed using the URL for the webhook receiver.

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

   4. In the Trigger section, ensure Push events is selected.

   5. Click Add webhook.

4. From the Webhooks settings page, verify connectivity by expanding the Test dropdown menu next to your webhook and selecting Push events.

   

   

   note

   This is safe to do because the test payload will lack the necessary details to successfully refresh Warehouse resources subscribed to the repository.

   If the test push event was delivered successfully, a success message will appear at the top of the Webhooks settings page.

   info

   If the test event is not successful, troubleshoot by clicking the Edit button next to your webhook, then scrolling down to the Recent events section to view details of the failed request.

info

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