How-To: GitHub Commit Status Notifications

Flux posts ✅/❌ status checks directly to GitHub after each reconciliation. Every commit on main shows whether the cluster successfully applied it — no need to check flux get ks -A manually.

See ADR-014 for the full decision record.

---

How It Works

git push → GitHub → Flux pulls (every 1m or on-demand)
                         ↓
              notification-controller
                         ↓ GitHub Commit Status API
              Commit page: "flux/kustomize-controller ✅"

Three resources work together:

Resource	Kind	Purpose
github-token	Secret (SOPS)	GitHub PAT with Commit statuses scope
github-status	Provider	Connects to GitHub Commit Status API
github-status	Alert	Watches all Kustomizations + HelmReleases, forwards events to Provider

---

Initial Setup

1. Create a GitHub PAT

Go to GitHub → Settings → Developer settings → Personal access tokens.

Fine-grained token (recommended): - Repository access: MarcSpeckmann/HomeKube - Permissions: Commit statuses → Read and write

Classic token: - Scope: repo:status (single checkbox under the repo group)

2. Encrypt and commit the token

# Edit the template — replace REPLACE_WITH_GITHUB_PAT with your token
$EDITOR notifications/github-token.sops.yaml

# Encrypt in-place using the HomeKube GPG key
sops --encrypt --in-place notifications/github-token.sops.yaml

# Verify decryption works
sops --decrypt notifications/github-token.sops.yaml

# Commit and push
git add notifications/github-token.sops.yaml
git commit -m "chore: add github notifications token"
git push

3. Verify

# Check Provider and Alert were created
kubectl get provider,alert -n flux-system

# Expected output:
# NAME                                  AGE   READY   STATUS
# provider.notification...github-status  1m    True    Initialized
#
# NAME                               AGE   READY   STATUS
# alert.notification...github-status  1m    True    Initialized

On the next git push, the GitHub commit page will show status checks named flux/source-controller, flux/kustomize-controller, etc.

---

Rotating the Token

# Edit — SOPS decrypts, opens $EDITOR, re-encrypts on save
sops notifications/github-token.sops.yaml

git add notifications/github-token.sops.yaml
git commit -m "chore: rotate github notifications token"
git push

# Force immediate pickup (otherwise Flux waits up to 1h)
flux reconcile kustomization notifications --with-source

---

Troubleshooting

No status checks appearing on GitHub

# 1. Check Provider is Ready
kubectl describe provider github-status -n flux-system
# Look for: Status: True, Reason: Initialized

# 2. Check notification-controller logs for API errors
kubectl logs -n flux-system deployment/notification-controller --tail=50 | grep -i error

# 3. Verify the secret has the correct key name (must be 'token', not 'password')
kubectl get secret github-token -n flux-system \
  -o jsonpath='{.data}' | python3 -c "import sys,json; print(list(json.load(sys.stdin).keys()))"
# Expected: ['token']

# 4. Verify the PAT has Commit statuses scope on GitHub
# GitHub → Settings → Developer settings → your token → check permissions

Provider shows "context deadline exceeded" or "403"

• 403: Token is missing Commit statuses write permission — recreate or update the token scope
• deadline exceeded: GitHub API unreachable from the cluster — check cilium connectivity test

Token expired or revoked

Flux will log 401 Unauthorized in notification-controller. Rotate the token (see above).