GitOps
GitOps is an operating model for infrastructure and applications. The desired state of every environment lives in Git, and a software agent inside each environment keeps the live system equal to it. Every change is a commit that can be reviewed, audited, and reverted, and nobody needs to change a cluster by hand.
The term was coined by Weaveworks in 2017, and the OpenGitOps working group published version 1.0 of the principles in 2021. The model builds on Infrastructure as Code, continuous delivery, and the Kubernetes controller pattern.
The problem it solves
Section titled “The problem it solves”Without a single source of truth, deployment drifts into habits that do not scale:
- Engineers run
kubectl applyfrom a laptop, so the cluster holds changes that no repository records. - Environments that were identical at launch diverge, and nobody can say how.
- A pipeline with cluster-admin credentials becomes the most valuable target in the organization.
- After an outage, rebuilding a cluster means replaying a history that exists only in people’s memory.
GitOps answers each of these with the same move: describe the end state in Git, and let an agent make reality match.
The four OpenGitOps principles
Section titled “The four OpenGitOps principles”| Principle | Official statement | In practice |
|---|---|---|
| Declarative | A system managed by GitOps must have its desired state expressed declaratively. | State is written as YAML (plain, Helm, or Kustomize) that describes the end result, not the steps to reach it. |
| Versioned and immutable | Desired state is stored in a way that enforces immutability, versioning, and retains a complete version history. | Git history is never rewritten, so any past state can be audited or restored. A rollback is a git revert. |
| Pulled automatically | Software agents automatically pull the desired state declarations from the source. | An agent near the target environment fetches from Git. CI does not push into the cluster. |
| Continuously reconciled | Software agents continuously observe actual system state and attempt to apply the desired state. | Agents run a feedback loop that detects drift and re-applies the declared state. |
Push and pull delivery
Section titled “Push and pull delivery”A traditional pipeline pushes: the CI system runs kubectl apply or helm install against the cluster. GitOps inverts this, and the cluster pulls its own configuration.
| Characteristic | Push (CI-driven) | Pull (agent-driven) |
|---|---|---|
| Trigger | A pipeline run executes the deployment | An in-cluster agent watches Git and pulls changes |
| Cluster credentials | CI holds long-lived kubeconfigs or admin tokens | Credentials stay inside the cluster |
| Network exposure | The cluster must be reachable from CI | The agent makes outbound connections to Git only |
| Drift detection | None. Manual changes go unnoticed until the next push | Continuous. Out-of-band changes are flagged |
| Reconciliation | One execution per pipeline run | A loop that never terminates |
| Disaster recovery | Re-run several pipelines in order | Install the agent in a fresh cluster and point it at the repository |
The reconciliation loop
Section titled “The reconciliation loop”GitOps applies the Kubernetes controller pattern to delivery.
flowchart LR
Git["Git repository<br/>desired state"] -->|"agent pulls"| Agent["GitOps agent"]
Agent -->|"observes"| Live["Live cluster<br/>actual state"]
Agent -->|"applies changes"| Live
- Developers and platform teams propose changes as pull requests.
- CI runs static checks, schema validation, and policy tests. Merging to the main branch updates the desired state.
- The agent compares the live state with the Git commit.
- If they differ, either because of a new commit or a manual change in the cluster, the agent synchronizes the cluster or alerts the team.
What goes in Git
Section titled “What goes in Git”Most teams keep application source and deployment configuration in separate repositories. The configuration repository is what the agent watches, and its history becomes the audit log of what ran where and when. A common layout:
deploy-config/├── apps/│ └── catalog-api/│ ├── base/ # manifests shared by every environment│ └── overlays/│ ├── dev/│ ├── staging/│ └── prod/ # only the differences: replicas, limits, hostnames└── platform/ ├── cert-manager/ └── monitoring/Environments are directories, not branches. A directory per environment makes every environment visible at once and avoids merge conflicts between long-lived branches. Repository strategies compares the options in more depth, and Application organisation and GitOps shows how Kustomize overlays and Helm values keep the per-environment differences small.
Limits of the model
Section titled “Limits of the model”- Secrets cannot sit in Git in plain text. Use an external secrets operator or encrypted manifests, and keep only references in the repository. See secrets management.
- Merge rights are deploy rights. Branch protection, required reviews, and code owners on the configuration repository are now part of the security boundary.
- Eventual consistency. A merge does not mean the change is live. Health checks, notifications, and dashboards must report the result, because the pipeline no longer does.
- Not everything is declarative. Database migrations, one-off jobs, and data fixes need hooks or a separate process.
- The agent is critical infrastructure. If it stops, drift goes unnoticed. Monitor it like any production service.
Go deeper
Section titled “Go deeper”- Best practices covers repository layout, DRY configuration, trunk-based workflow, rendered manifests, promotion tools, and progressive delivery.
- Secrets management compares External Secrets Operator, Sealed Secrets, and SOPS.
Tooling
Section titled “Tooling”Argo CD and Flux are the two main open-source GitOps controllers in the CNCF ecosystem. This section teaches Argo CD.