Skip to content

ADR-014: Flux Notifications → GitHub Commit Status

Status

Accepted

Date

2026-03-21

Context

After a git push to main, Flux reconciles the change but the result is only visible by running flux get ks -A or checking cluster logs. There is no feedback on GitHub itself — commit pages show no status checks, and it is not obvious from the repository whether the cluster successfully applied a given commit.

The notification-controller is already deployed (installed as part of the standard Flux bootstrap). It supports a github Provider type that posts Commit Status API entries, surfacing reconciliation results directly on GitHub commit pages.

Decision

Add a Flux Provider (type: github) and Alert to the flux-system namespace. The Alert watches the root GitRepository, all Kustomization objects, and all HelmRelease objects, forwarding events to the GitHub Commit Status API.

Resources added:

notifications/
  kustomization.yaml          # Kustomize manifest list
  provider.yaml               # notification.toolkit.fluxcd.io/v1beta3 Provider
  alert.yaml                  # notification.toolkit.fluxcd.io/v1beta3 Alert
  github-token.sops.yaml      # SOPS-encrypted GitHub PAT (repo:status scope)
clusters/local/notifications.yaml  # Flux Kustomization object

Provider configuration:

apiVersion: notification.toolkit.fluxcd.io/v1beta3
kind: Provider
spec:
  type: github
  address: https://github.com/MarcSpeckmann/HomeKube
  secretRef:
    name: github-token  # key: token

Alert event sources:

Source Scope
GitRepository/flux-system Source fetch status (did Flux pull the latest commit?)
Kustomization/* (flux-system ns) Apply status for all Kustomizations
HelmRelease/* (all namespaces) Helm install/upgrade status

GitHub PAT scope: repo:status only. This scope is write-only to commit statuses and grants no read access to repository content or code.

The token is stored as a SOPS-encrypted secret using the existing HomeKube GPG key (fingerprint CF7169E94481219626AF34290D18AE7E58FB2D45) and the existing sops-gpg decryption setup.

Alternatives Considered

Option Reason Not Chosen
Slack / Teams Alert No Slack/Teams workspace in use for this project
Grafana alert annotations Grafana is already available but does not surface on the GitHub commit view
GitHub Actions only Only runs on push events, not on cluster-side reconciliation failures (e.g. drift)
No notifications Reconciliation failures are silent — violates observability principle

Consequences

Positive

  • Every commit on GitHub shows ✅/❌ status checks from Flux
  • Reconciliation failures are immediately visible without checking the cluster
  • Uses existing notification-controller — no additional component installs
  • Token scope is minimal (repo:status only)

Negative

  • Requires a GitHub PAT to be created and rotated manually
  • Flux posts one status per event source — busy repos may generate many status entries per commit
  • GitHub API rate limits apply (rarely a concern for a single-cluster sandbox)

Setup Checklist

  1. Create a GitHub PAT: Settings → Developer settings → Fine-grained tokens (or classic repo:status)
  2. Replace REPLACE_WITH_GITHUB_PAT in notifications/github-token.sops.yaml
  3. Encrypt: sops --encrypt --in-place notifications/github-token.sops.yaml
  4. Commit and push — Flux reconciles notifications Kustomization
  5. Verify: kubectl get provider,alert -n flux-system
  6. On the next push, the GitHub commit page will show "flux/kustomize-controller" checks