Skip to content
Documentation Background

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.


Without a single source of truth, deployment drifts into habits that do not scale:

  • Engineers run kubectl apply from 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.


PrincipleOfficial statementIn practice
DeclarativeA 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 immutableDesired 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 automaticallySoftware 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 reconciledSoftware 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.

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.

CharacteristicPush (CI-driven)Pull (agent-driven)
TriggerA pipeline run executes the deploymentAn in-cluster agent watches Git and pulls changes
Cluster credentialsCI holds long-lived kubeconfigs or admin tokensCredentials stay inside the cluster
Network exposureThe cluster must be reachable from CIThe agent makes outbound connections to Git only
Drift detectionNone. Manual changes go unnoticed until the next pushContinuous. Out-of-band changes are flagged
ReconciliationOne execution per pipeline runA loop that never terminates
Disaster recoveryRe-run several pipelines in orderInstall the agent in a fresh cluster and point it at the repository

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
  1. Developers and platform teams propose changes as pull requests.
  2. CI runs static checks, schema validation, and policy tests. Merging to the main branch updates the desired state.
  3. The agent compares the live state with the Git commit.
  4. 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.

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.


  • 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.

  • 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.

Argo CD and Flux are the two main open-source GitOps controllers in the CNCF ecosystem. This section teaches Argo CD.