All jobs

Add a GitHub Webhook Receiver to a Flux Cluster

Yes. An agent adds a Flux Receiver and a Gateway API route for GitHub push webhooks so a push reconciles at once, validates the manifests and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads the repository's layout before it adds a resource to it. In a Flux monorepo like fluxcd/flux2-kustomize-helm-example, clusters/staging/ holds what flux bootstrap github --components-extra=source-watcher --path=clusters/staging syncs: a flux-system/ directory whose gotk-components.yaml and gotk-sync.yaml are placeholders until bootstrap writes them, with a kustomization.yaml that patches the controllers for --concurrent=20; artifacts.yaml, an ArtifactGenerator that reads the flux-system GitRepository and splits it into an infrastructure and an apps ExternalArtifact; infrastructure.yaml, two Kustomizations named infra-controllers and infra-configs with an interval of one hour; and apps.yaml, the apps Kustomization with the same interval. infrastructure/controllers/ installs cert-manager and Envoy Gateway from OCI charts, and infrastructure/configs/gateway.yaml defines a GatewayClass named envoy and a Gateway named envoy in envoy-gateway-system with one HTTP listener on port 80 that allows routes from every namespace. .sourceignore limits what Flux reads to apps/, clusters/ and infrastructure/, scripts/validate.sh validates every manifest and overlay with flux-schema using .fluxschema.yml, and .github/workflows/test.yaml runs that validation and flux migrate -f . --yes on pull requests. With intervals of an hour, a push waits up to an hour unless something tells the source controller to look.

Flux's notification controller is that something. Its docs describe the Receiver resource in notification.toolkit.fluxcd.io/v1: type: github, an events list such as ping and push, a secretRef naming a Secret with a token key, and resources listing what to reconcile, for this repository the GitRepository named flux-system in flux-system. The controller listens on port 9292, the webhook-receiver Service in flux-system maps that to port 80, and the webhook guide exposes it through an Ingress, a LoadBalancer or a Gateway API HTTPRoute to webhook-receiver on port 80. Once the Receiver is ready its status.webhookPath reads /hook/ and a hash of the token, name and namespace; GitHub's webhook gets that path on the exposed address and the same token as its secret, and the controller checks the X-Hub-Signature header on every delivery. The guide also suggests rate limiting on the route, since each delivery becomes a Kubernetes API call.

The agent adds clusters/staging/receiver.yaml, a Receiver named github-receiver in flux-system for ping and push events, with secretRef set to webhook-token and the flux-system GitRepository as its resource, because the ArtifactGenerator and the three Kustomizations all descend from that source. It adds infrastructure/configs/webhook-receiver-route.yaml, an HTTPRoute in flux-system whose parentRefs name the envoy Gateway in envoy-gateway-system with the http section, a placeholder hostname flux-webhook.staging.example.com, a path match on /hook/ and a backendRefs entry for webhook-receiver on port 80, and lists it in infrastructure/configs/kustomization.yaml. The same two files go under clusters/production/ and are patched for the production hostname in clusters/production/infrastructure.yaml, the way the Let's Encrypt server already is. The token is never committed: the README gets the guide's two commands, generating a token and kubectl -n flux-system create secret generic webhook-token --from-literal=token=$TOKEN, with a note that a repository already using SOPS encrypts it there instead.

Then the agent checks it. It installs the Flux CLI from the v2.10.0 release, the current one, the flux-schema plugin and kustomize, and runs scripts/validate.sh, which builds every overlay and validates the new Receiver and HTTPRoute against the ecosystem schemas, then flux migrate -f . --yes to show the API versions are current. For an end-to-end check it follows e2e.yaml: the sandbox has no Docker, so it installs it with sudo apt-get install -y docker.io, starts dockerd, creates a kind cluster with the workflow's node image, runs flux install --components-extra source-watcher, creates the flux-system source and Kustomization the workflow creates, applies the token Secret and the Receiver, and reads kubectl -n flux-system get receiver github-receiver until it is ready and shows its webhook path. It posts a signed test payload from inside the cluster to webhook-receiver and reads the notification controller's log to see the event accepted.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add a GitHub webhook receiver to this Flux repository so a push reconciles the clusters at once. Read the README, .sourceignore, .fluxschema.yml, scripts/validate.sh, .github/workflows/test.yaml and e2e.yaml, every file under clusters/, infrastructure/ and apps/ first. For staging and production add a Receiver of type github for ping and push events, with a secretRef to a webhook-token Secret and the flux-system GitRepository as its resource, and an HTTPRoute in flux-system attached to the existing envoy Gateway that routes /hook/ on a placeholder hostname to the webhook-receiver service on port 80, listed in infrastructure/configs/kustomization.yaml and patched per cluster for the hostname. Do not commit a token; add the commands that create the Secret to the README with a note on SOPS. Install the Flux CLI, flux-schema and kustomize, run scripts/validate.sh and flux migrate, then install Docker and kind, repeat the e2e workflow's steps, apply the Secret and the Receiver, wait for the Receiver to be ready, show its webhook path, post a signed test delivery to the service from inside the cluster and read the notification controller's log. Open a pull request with the commands and their output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

The pull request adds clusters/staging/receiver.yaml, clusters/production/receiver.yaml and infrastructure/configs/webhook-receiver-route.yaml, and changes infrastructure/configs/kustomization.yaml, clusters/production/infrastructure.yaml and the README. Its description quotes the scripts/validate.sh summary with the new resources counted as valid, the flux migrate result, the kubectl get receiver line with the webhook path from the kind cluster, the controller log line for the test delivery, and the GitHub webhook settings to enter: the payload URL, JSON content type and the token as the secret.

A reviewer checks the hostnames, whether the route needs TLS through the cert-manager issuer the repository already has, whether a rate limit belongs on the route, and whether production should receive push events for main only, which the Receiver cannot filter and GitHub's webhook settings can. After merging and creating the Secret on each cluster, the reader adds the webhook in the repository's settings and the next push reconciles within seconds instead of an hour.

Run it on every new cluster directory

A platform team's server sends this body once per repository it bootstraps, with that repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried start returns the run already started. The API key's webhook_url reports each run as it ends, with the pull request's address in the session, and the engineer who owns the cluster reviews it from the console.

A fleet with one repository per cluster sends one request per repository; a monorepo that gains a third cluster directory gets a follow-up run with input naming it.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

A Receiver is a few lines of YAML, and whether it works is a question only a cluster answers: the Service name, the port, the hash in the webhook path and the signature check. The agent builds a kind cluster in its own sandbox, installs Flux as the repository's own e2e workflow does, applies the resource, reads its status and the controller's log, and keeps every command and its output in the run's record, so the pull request shows the receiver accepting a delivery.

The change fits the repository as written: the flux-system source every Kustomization descends from, the Envoy Gateway and the configs overlay that already carry the cluster's routes, the per-cluster patch pattern in infrastructure.yaml, and the schema validation CI already runs. Ten Flux repositories get ten pull requests, each wired to that cluster's own gateway or ingress.

Frequently asked questions

Why target the flux-system GitRepository and not the apps Kustomization?

Because in this repository the ArtifactGenerator and all three Kustomizations read from that one GitRepository; a push event that refreshes it lets source-watcher regenerate the artifacts and the kustomize controller reconcile what changed. A Receiver can list more resources, and the pull request shows where to add an ImageRepository for image events.

Where does the token live?

In a Secret named webhook-token in flux-system, created on each cluster with the kubectl create secret command from the README, and entered as the secret in GitHub's webhook settings. It is not committed; a repository that already encrypts Secrets with SOPS adds it there so Flux creates it.

Does this need an Ingress controller?

Not here. The repository already runs Envoy Gateway with a Gateway that admits routes from every namespace, so an HTTPRoute to the webhook-receiver Service is enough. A cluster without a gateway uses the Ingress or LoadBalancer Service from the Flux guide instead, which the pull request names.

Can anyone who finds the URL trigger a reconcile?

The path contains a hash of the token and the controller verifies GitHub's X-Hub-Signature with that token, so a request without the right secret is refused. The Flux guide still recommends rate limiting on the route, since each accepted delivery becomes an API call, and the pull request leaves that to the reviewer.

More Flux jobs

More jobs like this: Hand off a long task

Keep reading