Documentation survey

Using Webhooks Instead of Polling

By default, SUSE® Rancher Prime Continuous Delivery uses polling (every 15 seconds by default) to pull from a Git repository. Polling works well for small installations (up to a few tens of repositories).

For installations with many repositories or when you want to reduce latency (the time between a Git push and SUSE® Rancher Prime Continuous Delivery reacting to it), configure webhooks instead of polling.

SUSE® Rancher Prime Continuous Delivery currently supports these providers:

  • Azure DevOps

  • GitHub

  • GitLab

  • Bitbucket

  • Bitbucket Server

  • Gogs

1. Configure the Webhook Service

SUSE® Rancher Prime Continuous Delivery uses a gitjob service to handle webhook requests. Create an Ingress that points to the gitjob service.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: webhook-ingress
  namespace: cattle-fleet-system
spec:
  rules:
  - host: your.domain.com
    http:
      paths:
        - path: /
          pathType: Prefix
          backend:
            service:
              name: gitjob
              port:
                number: 80

If you want to make the webhook available using the same host name as Rancher or another service, use the following YAML. This example uses the NGINX Ingress Controller and exposes the webhook at http://your.domain.com/gitjob.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/use-regex: "true"
    nginx.ingress.kubernetes.io/rewrite-target: /$2
  name: webhook-ingress
  namespace: cattle-fleet-system
spec:
  rules:
  - host: your.domain.com
    http:
      paths:
        - path: /gitjob(/|$)(.*)
          pathType: ImplementationSpecific
          backend:
            service:
              name: gitjob
              port:
                number: 80

You can configure TLS on Ingress for secure communication.

2. Configure the Webhook Callback URL

Go to your Git provider and configure the webhook callback URL. The following image shows an example from GitHub.

image

../../images/webhook.png[]

Configuring a secret is optional. The secret is used to validate the webhook payload since the payload shouldn’t be trusted by default.

If your webhook endpoint is publicly accessible, it’s strongly recommended to configure a secret. If you set up a secret, continue with step 3.

Only application/json is supported due to limitations in the webhook library.

When a webhook is configured, the polling interval automatically adjusts to one hour.

3. (Optional) Configure a Webhook Secret

The webhook secret validates the payload sent from your Git provider. Each supported provider uses a specific key name in the Kubernetes secret.

Provider Kubernetes Secret Key

GitHub

github

GitLab

gitlab

Bitbucket

bitbucket

Bitbucket Server

bitbucket-server

Gogs

gogs

Azure DevOps

azure-username

Azure DevOps

azure-password

Option 1: Configure a Cluster-Wide Secret

In this approach, the secret applies to the entire cluster, and all GitRepos use it automatically. You don’t need to reference it in individual GitRepo definitions.

When a payload is received, SUSE® Rancher Prime Continuous Delivery checks if the secret exists (gitjob-webhook in the cattle-fleet-system namespace) and uses the appropriate key for validation.

For GitHub:

kubectl create secret generic gitjob-webhook \
  -n cattle-fleet-system \
  --from-literal=github=webhooksecretvalue

For Azure DevOps:

  1. Enable Basic Authentication in Azure.

  2. Create a secret containing the credentials.

kubectl create secret generic gitjob-webhook \
  -n cattle-fleet-system \
  --from-literal=azure-username=user \
  --from-literal=azure-password=pass123

Option 2: Configure a Secret per GitRepo

You can define a unique webhook secret for each GitRepo. Create the secret in the same namespace as the GitRepo, and reference it using the webhookSecret field in the spec.

Example:

apiVersion: fleet.cattle.io/v1alpha1
kind: GitRepo
metadata:
  name: simple
  namespace: fleet-local
spec:
  repo: "https://github.com/rancher/fleet-examples"
  paths:
    - simple
  disablePolling: true
  webhookSecret: webhook-secret-name

If both a cluster-wide secret and a per-GitRepo secret exist, SUSE® Rancher Prime Continuous Delivery uses the per-GitRepo secret.

4. Test the Webhook

Go to your Git provider and test the webhook connection. You should receive an HTTP response code confirming the webhook delivery.