What GitOps Actually Means
Summary
- GitOps is an operating model where the desired state of a system lives in Git, and an in-cluster controller continuously reconciles the running cluster toward that state.
- Insight: GitOps is not "CI/CD that runs kubectl apply." The defining trait is a controller inside the cluster that pulls and reconciles, not a pipeline that pushes.
- Key Concepts: declarative desired state, Git as source of truth, continuous reconciliation, pull-based delivery, drift correction.
- When to Use: Kubernetes fleets where auditability, rollback, and multi-cluster consistency matter more than the fastest possible imperative change.
- Limitations/Trade-offs: Every change goes through Git, which adds latency and ceremony; secrets and non-declarative resources need extra tooling.
- Related Topics: Argo CD, Flux, drift detection, and the reconciliation loop that ties them together.
Foundations
GitOps names a specific pattern for operating declarative infrastructure, most commonly Kubernetes.
The idea is simple to state. The entire desired state of your workloads lives as declarative files in a Git repository.
A software agent running inside the cluster watches that repository. It compares the declared state against what is actually running and makes the cluster match.
The mental model is a control loop, the same one Kubernetes itself uses internally. A controller observes desired state, observes actual state, and drives the difference to zero.
GitOps extends that loop outward. Instead of the desired state living only in etcd, it lives in Git, and a dedicated controller keeps etcd synchronized with the repository.
This is why people say "the cluster is a projection of Git." Git is authoritative; the cluster is a materialized view of it.
Four principles define the model. The system is declarative, versioned and immutable in Git, pulled automatically, and continuously reconciled.
Declarative means you describe the end state, not the steps. A Deployment manifest says "run three replicas of this image," not "scale up by one."
Versioned and immutable means every desired state is a Git commit. You never mutate history; you add new commits, and you can check out any prior state exactly.
Pulled automatically means an agent inside the cluster fetches changes. Nothing outside the trust boundary needs cluster credentials.
Continuously reconciled means the agent does not fire once and stop. It re-checks on an interval and after every relevant event, forever.
Mechanics & Interactions
Concretely, a GitOps tool such as Argo CD or Flux runs as a set of controllers in your cluster.
These controllers hold read access to one or more Git repositories, and read/write access to the Kubernetes API of the cluster they manage.
On each reconciliation, the controller renders the desired manifests. Rendering may mean running Kustomize, templating a Helm chart, or reading plain YAML.
It then diffs the rendered objects against the live objects returned by the API server. The diff is field-by-field on the resources under management.
If there is a difference, the controller applies the desired manifests using a server-side apply or an equivalent patch, bringing live state back to declared state.
This is the reconciliation loop. It is what makes GitOps different from a push pipeline.
Contrast the two delivery models directly. In push-based CI/CD, a pipeline runs kubectl apply or helm upgrade from a runner after tests pass.
Push works, but the runner needs cluster credentials, the apply happens once, and nothing corrects the cluster if it drifts afterward.
In pull-based GitOps, the pipeline's job ends at "commit the new manifest to Git." The in-cluster agent notices the commit and does the apply.
The agent keeps applying on every loop, so if someone hand-edits a resource, the next reconciliation overwrites it. That standing correction is the core value.
Credentials also flow the safe direction. External systems never hold kubeconfig access; the agent reaches out to Git, so the cluster's write path stays inside its own trust boundary.
Sync can be automatic or gated. Many teams let non-production clusters auto-sync and require a manual promotion or approval for production.
Advanced Considerations & Applications
GitOps scales cleanly to many clusters because each cluster runs its own agent pointed at the same or per-cluster repositories.
A single control-plane cluster can also manage remote clusters. Argo CD registers external clusters and applies to them; Flux is typically installed per cluster.
Repository structure becomes a real design decision. A common contract separates platform manifests (ingress, policy, operators) from application manifests, which is covered in GitOps Best Practices.
Not everything is naturally declarative. Secrets must never sit in plaintext Git, so teams use Sealed Secrets, SOPS-encrypted files, or an external secrets operator that pulls from a vault.
Ordering matters for stateful stacks. CRDs must exist before the custom resources that use them, which is why Argo CD offers sync waves and Flux offers dependsOn.
Reconciliation frequency is a tuning knob. Faster loops catch drift sooner but add API-server load; typical intervals sit between one and five minutes with event-driven webhooks for immediacy.
Rollback is a Git operation. To revert a bad release, you revert the commit, and the agent reconciles the cluster back to the previous known-good state.
That property makes incident response calmer. Recovery is git revert plus a sync, not a scramble to remember the previous image tag.
Common Misconceptions
"GitOps is just running kubectl in a pipeline." No. Without an in-cluster reconciling controller, you have push-based automation, not GitOps.
"GitOps replaces CI." It does not. CI still builds, tests, and produces images; GitOps handles continuous delivery of declared state. CI writes to Git, GitOps reads from it.
"GitOps means one giant repo of YAML." Structure is a choice. Teams use one repo, a repo per environment, or split platform and app repos with clear ownership.
"GitOps and Docker are competitors." They are different layers. Docker with BuildKit builds and ships images; the node runtime is containerd via CRI. GitOps decides which of those images runs where.
"Reconciliation will fight my legitimate manual changes." Only changes to managed fields are reverted. That is the point, and emergency edits should be codified back into Git.
FAQs
Does GitOps require Kubernetes? In practice it is strongest on Kubernetes because of the native controller model, but the pattern applies to any declarative, continuously reconciled system.
Where do container images fit in? Your registry holds images built by Docker/BuildKit; Git holds the manifests that reference specific image digests or tags. Image automation can bump those references.
Is Argo CD or Flux "more GitOps"? Neither. Both implement the same pull-and-reconcile model with different ergonomics. See Argo CD and Flux.
How do I know when something drifted? The agent reports sync status and shows the live-versus-desired diff, which Drift Detection covers in depth.
Can I still use kubectl for debugging? Yes, for reads and ephemeral debug pods. Persistent changes should go through Git or they will be reconciled away.
What runs the containers on the node? containerd via the CRI runs pods; Docker Engine is for build and local development, not the in-cluster runtime.
Related
Stack versions: This page was written for Kubernetes 1.36.2, Docker Engine 29.6.1 (BuildKit default), containerd (CRI runtime on nodes), Helm 3, Compose v2, Argo CD (latest - verify at build), and Gateway API (GA - verify controller support at build).