Bitbucket Webhook Receiver

The Bitbucket webhook receiver responds to repo:push events originating from Bitbucket 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 Bitbucket webhook receiver also works with Bitbucket Server and Bitbucket Data Center, although some URLs in this document may need to be adjusted accordingly.

Configuring the Receiver

A Bitbucket webhook receiver must reference a Kubernetes Secret resource with a secret key in its data map. This shared secret will be used by Bitbucket 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: bb-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: bb-wh-receiver
    bitbucket:
      secretRef:
        name: bb-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 Bitbucket

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

1. Navigate to https://bitbucket.org/<workspace>/<repository>/admin/webhooks where <workspace> has been replaced with a Bitbucket workspace and <repository> has been replaced with the name of a repository belonging to that workspace and for which you are an administrator.

2. Click Add webhook.

3. Complete the Add new webhook form:

   

   1. Enter a descriptive name in the Title field.

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

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

      danger

      Do not use the Generate secret button in the Bitbucket UI.

      Kargo incorporates the secret's value into the URL it generates for the webhook receiver. Using a secret in this field other than the one already referenced by the receiver's configuration will require revisiting that configuration and doing so will change the receiver's URL.

   4. Under Status, ensure Active is selected.

   5. Under Triggers → Repository, ensure Push is selected.

   6. Click Save.

4. Verify that the new webhook appears under Repository hooks.

5. If you'd like to record outbound webhook requests for troubleshooting purposes:

   1. Click the View requests link next to your webhook.

   2. Click on Enable History.

   

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 Bitbucket Docs.