# 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 Rush](https://cloud.getrush.ai/run/add-webhook-receiver/flux/). Opens 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 `Kustomization`s 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 `Kustomization`s 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`

```json
{
  "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.

## 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 `Kustomization`s 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

- [Review Flux Manifest Changes in Pull Requests](https://getrush.ai/run/review-kubernetes-manifests/flux/)
- [Add Canary Rollouts to a Flux Repository](https://getrush.ai/run/add-canary-rollouts/flux/)
- [Add Cosign Signature Verification to Flux Helm Sources](https://getrush.ai/run/add-cosign-verification/flux/)

## More jobs like this: Hand off a long task

- [Add WebSockets to an aiohttp App](https://getrush.ai/run/add-websockets/aiohttp/)
- [Add WebSockets to a Cloudflare Worker with Durable Objects](https://getrush.ai/run/add-websockets/cloudflare-workers/)
- [Add WebSockets to a Fastify App](https://getrush.ai/run/add-websockets/fastify/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
