Follow a deployment revision through FluxCD

When to use this

A commit has reached Git, but the expected application version is not running. Start by separating three questions: did Flux fetch the source, did it apply the desired resources, and did those resources become ready?

My platform work at jaraco uses FluxCD and GitHub Actions. I wrote this note because GitOps failures can look confusing when CI is green but the cluster is still not running the expected version. The commands below are a general diagnostic guide based on Flux’s public documentation, not a copy of an internal runbook.

1. Confirm the context

kubectl config current-context
flux check
flux get all -A --status-selector ready=false

Confirm the intended cluster before proceeding. flux check reports controller readiness and installation checks; the final command narrows attention to resources that are not ready.

2. Check the source revision

flux get sources all -A
kubectl get gitrepositories.source.toolkit.fluxcd.io -A

Look at readiness, suspension, and the observed revision. If the source is not ready, investigate access, the selected branch or tag, and source-controller events before investigating the workload.

3. Check the applying controller

flux get kustomizations -A
flux get helmreleases -A
flux logs --all-namespaces --level=error
kubectl get events -n flux-system --field-selector type=Warning

For a Kustomization, check its referenced source, path, dependencies, and reconciliation message. For a HelmRelease, check the chart source and version as well as the install or upgrade result. Fully qualified resource names avoid ambiguity when more than one Helm controller is installed.

4. Inspect workload readiness

A source can be ready while a workload is not. Image-pull failures, scheduling constraints, storage mounts, or application readiness checks may hold up the rollout. Continue with the stalled-rollout runbook once the desired revision has reached the cluster.

5. Recover through the desired state

Correct the configuration or revert the relevant change in Git, then watch the source and applying controller converge. Reconciliation can be requested after fixing the cause; repeatedly requesting it without a change is not a diagnosis.

Close the investigation only when the intended revision is observed, the applying resources are ready, and the application’s own signals are healthy. The goal is not to run every command, but to keep the source, controller, workload, and user-facing behavior in the same story.

Source

Flux troubleshooting cheatsheet, reviewed on 13 September 2026. Check the documentation matching your installed Flux version when diagnosing a specific controller behavior.