Flux integration guide

This guide walks through the full setup: creating a deploy hook in gittan.eu, configuring a Flux Receiver, and listing the right resources so image scans and automations fire immediately instead of waiting for the default poll interval.

Prerequisites

• A gittan.eu organization on a paid plan (deploy hooks require a subscription)
• Flux installed in your cluster with the notification-controller and image-automation-controller
• At least one ImageRepository and ImagePolicy for the images you want to track

How it works

Without the hook, each step waits for its poll interval (typically 1–5 minutes). With it, the chain fires within seconds of image publish.

Step 1: Create a deploy hook in gittan.eu

Use the CLI or go to Admin → Integrations:

gittan deploy hooks create \
  --url https://<your-receiver-url> \
  --events image-published

gittan.eu returns an HMAC secret. Copy it — you will need it for the Flux Receiver. The secret is shown once and cannot be retrieved later.

If you also want pushes to gitops repos to trigger Flux immediately, create a second hook:

gittan deploy hooks create \
  --url https://<your-receiver-url> \
  --events push \
  --repo-filter "*-gitops"

Step 2: Store the HMAC secret in your cluster

Create a Kubernetes Secret in the flux-system namespace containing the HMAC token:

kubectl create secret generic flux-receiver-token \
  --namespace flux-system \
  --from-literal=token=<your-hmac-secret>

In production, manage this secret through your existing secret management (SOPS, Sealed Secrets, External Secrets, etc.) rather than raw kubectl.

Step 3: Create the Flux Receiver

The Receiver validates the HMAC signature and triggers the listed resources:

apiVersion: notification.toolkit.fluxcd.io/v1
kind: Receiver
metadata:
  name: gittan-images
  namespace: flux-system
spec:
  type: generic-hmac
  secretRef:
    name: flux-receiver-token
  resources:
    # Each ImageRepository you want to scan immediately
    - apiVersion: image.toolkit.fluxcd.io/v1beta2
      kind: ImageRepository
      name: my-api
      namespace: flux-system
    - apiVersion: image.toolkit.fluxcd.io/v1beta2
      kind: ImageRepository
      name: my-web
      namespace: flux-system
    # The automation that commits updated tags
    - apiVersion: image.toolkit.fluxcd.io/v1beta2
      kind: ImageUpdateAutomation
      name: my-apps
      namespace: flux-system

Which resources to list

You do not need to list ImagePolicy resources — they reconcile automatically when their ImageRepository finds a new tag.

Step 4: Get the webhook URL

After the Receiver is applied, Flux generates a webhook path:

kubectl -n flux-system get receiver gittan-images \
  -o jsonpath='{.status.webhookPath}'

The full URL is your ingress or load balancer address plus this path. If the receiver is cluster-internal only (no ingress), the URL is:

http://webhook-receiver.flux-system.svc.cluster.local<webhookPath>

Go back to gittan.eu and update the deploy hook URL to this address.

Step 5: Image policy markers

For ImageUpdateAutomation to know which lines to update, add a marker comment on each image line in your manifests:

containers:
  - name: api
    image: images.gittan.eu/acme/api:20261021-120000-abc1234 # {"$imagepolicy": "flux-system:my-api"}

The value flux-system:my-api must match the namespace and name of your ImagePolicy.

Testing

Push a change to a repo with a pipeline that publishes an image. Then watch the Receiver events:

kubectl -n flux-system describe receiver gittan-images

You should see a ReconciliationRequested event within seconds of the image being published. The full chain — scan, policy, automation commit, GitRepository fetch, Kustomization apply — typically completes in under 30 seconds.

Combining with deploy feedback

Deploy hooks push outward (gittan.eu → your cluster). For the return path — your cluster reporting back that a release landed — see deploy feedback. Together they give you full deployment tracking from commit to production.