flux-ghcr-image-automation

Flux GHCR Image Automation

Goal

Create a reliable GitOps image release loop:

1. GitHub Actions builds and pushes a container image to GHCR.
2. Flux image-reflector-controller discovers the new tag or digest.
3. Flux image-automation-controller commits the selected image reference back to Git.
4. Flux kustomize-controller applies that commit and rolls the Kubernetes workload.

Prefer traceable, orderable image tags over mutable-only latest deployments. The operator should be able to answer "which Git commit produced this running pod?" from the image tag.

When Starting

Inspect the repo and cluster shape before editing:

• .github/workflows/*.yml
• Dockerfile
• kustomization/**
• any ImageRepository, ImagePolicy, ImageUpdateAutomation, Deployment, and Flux Kustomization resources
• the current branch name and default branch
• whether the Flux app Kustomization uses targetNamespace

If a live cluster is available and the user is debugging a rollout, inspect live state before changing files:

flux get images all -n <image-resource-namespace>
kubectl get kustomization -A -o wide
kubectl describe imageupdateautomation <name> -n <namespace>
kubectl get deploy <name> -n <namespace> -o yaml
kubectl get gitrepository -A -o wide

Design Rules

• Do not rely on plain sha-* tags for "latest commit" selection. SHA strings identify commits but do not sort by time.
• Prefer branch, short SHA, and timestamp tags for branch builds:

<branch>-<short-git-sha>-<unix-timestamp>

• Configure Flux ImagePolicy to filter the branch tag pattern, extract the timestamp, and use numerical ordering.
• Keep Flux image update commits from triggering fresh image builds by ignoring the manifest paths that Flux mutates, commonly kustomization/**.
• Keep the inline Flux setter comment on every image field Flux should update.
• Make the image setter comment reference the namespace where the ImagePolicy actually exists after Flux applies the manifests.
• When a Flux Kustomization has targetNamespace, remember that namespaced resources without an explicit namespace may land in that target namespace.
• Set ImageUpdateAutomation.spec.sourceRef.namespace when the referenced GitRepository is in a different namespace.
• Keep ImageUpdateAutomation.update.path pointed at the directory that contains the file with the image setter comment.