GitOps is a way of operating infrastructure and applications where Git is the single source of truth for what should be running, and an automated agent continuously reconciles the actual state of the system to match it. The term was coined by Weaveworks in 2017, but the underlying idea — declarative desired state, version control, automated reconciliation — predates it. What GitOps added was a specific set of practices and a set of tools that made the pattern practical for Kubernetes.
This guide covers what GitOps actually means (not just the marketing definition), how the reconciliation loop works, how ArgoCD and Flux compare, and where GitOps genuinely helps versus where it adds unnecessary complexity.
The four GitOps principles
The OpenGitOps project (a CNCF working group) defines GitOps around four principles:
1. Declarative. The desired state of the entire system is expressed declaratively. This means Kubernetes YAML manifests, Helm chart values, Kustomize overlays — not imperative scripts. "Apply these manifests" rather than "run these commands." The advantage: the desired state can be stored, diffed, and audited.
2. Versioned and immutable. The desired state is stored in a versioning system (Git) that enforces immutability of history. Every change has a timestamp, an author, and a hash. Rollback means reverting a commit. Audit means reading the commit log. You always know what changed, when, and who approved it.
3. Pulled automatically. Approved changes are automatically applied to the system. The GitOps agent inside the cluster watches the Git repository and pulls changes — the cluster initiates the connection, not external systems. This is a security advantage: you don't need to give CI/CD systems credentials to access the cluster. The cluster's outbound network needs to reach Git; nothing external needs inbound access to the API server.
4. Continuously reconciled. Software agents continuously compare actual state with desired state and automatically correct any divergence. If someone manually changes a Kubernetes resource (kubectl edit), the GitOps agent detects the drift and reverts it. This is the enforcement mechanism.
How the reconciliation loop works
A GitOps controller runs inside the cluster. It watches one or more Git repositories (or OCI registries) and continuously runs a control loop:
- Fetch the latest desired state from the Git repository
- Read the actual state of the cluster from the Kubernetes API
- Compute the diff
- Apply changes to make actual state match desired state
- Wait for the reconciliation interval (typically 1–5 minutes) and repeat
This pull-based model contrasts with the push-based model used by traditional CI/CD pipelines. In push-based deployments, a pipeline runs after a merge and pushes changes to the cluster via kubectl apply or Helm. In pull-based GitOps, the cluster continuously checks whether it matches Git and corrects itself.
# Push-based CI/CD (traditional)
# Pipeline runs:
kubectl apply -f manifests/
# Cluster state = whatever kubectl apply did
# GitOps (pull-based)
# GitOps controller runs in cluster, continuously:
# 1. Reads desired state from git
# 2. Compares to actual cluster state
# 3. Applies the diff
# Cluster state = what's in Git (enforced, not just applied once)
The Git repository structure
GitOps works best when the application code repository and the deployment configuration repository are separate. This "app repo + config repo" pattern is the most common structure:
- App repo: source code, Dockerfile, application tests. CI pipeline builds images, tags them with the git commit SHA, pushes to a registry, then opens a PR against the config repo to update the image tag.
- Config repo: Kubernetes manifests, Helm values, Kustomize overlays. This is what the GitOps controller watches. Changes here trigger deployments; changes to the app repo trigger a CI pipeline that eventually updates the config repo.
# Config repo structure (example)
clusters/
production/
namespaces/
api/
deployment.yaml
service.yaml
hpa.yaml
database/
statefulset.yaml
service.yaml
staging/
namespaces/
api/
deployment.yaml # different image tag, lower resource requests
database/
statefulset.yaml
Some teams keep everything in one repo using directory structure or branch strategy to separate environments. Others use separate repos per environment or per cluster. There's no single right structure — the key is that everything that defines cluster state lives in version control.
ArgoCD
ArgoCD is the most widely adopted GitOps tool. It runs as a set of controllers in the cluster and exposes a web UI and CLI. The core concept is an Application resource that maps a Git repository path to a Kubernetes namespace:
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: api-production
namespace: argocd
spec:
project: default
source:
repoURL: https://github.com/mycompany/config-repo
targetRevision: main
path: clusters/production/namespaces/api
destination:
server: https://kubernetes.default.svc
namespace: api
syncPolicy:
automated:
prune: true # delete resources removed from git
selfHeal: true # revert manual changes
syncOptions:
- CreateNamespace=true
ArgoCD's web UI shows the sync status of every Application — green (in sync), yellow (out of sync), red (degraded). Out-of-sync resources show exactly what differs between the cluster and Git. This visual diff is one of ArgoCD's most valued features for operators who want to understand deployment state at a glance.
ArgoCD uses an app of apps pattern for managing many Applications: a root Application points to a directory of Application manifests, which ArgoCD then deploys. This bootstraps an entire cluster from a single ArgoCD Application.
ArgoCD's approach to Helm and Kustomize
ArgoCD natively supports Helm charts and Kustomize overlays. You can point an Application at a Helm chart in a Git repo or a remote Helm repository, and specify values files or inline value overrides. Kustomize overlays let you maintain a base configuration and layer environment-specific patches on top.
Flux
Flux takes a more composable, Kubernetes-native approach. Instead of a single Application CRD, Flux uses several specialized CRDs that each handle a specific concern:
- GitRepository: defines a Git source (URL, branch, interval, credentials)
- HelmRepository: defines a Helm chart source
- OCIRepository: defines an OCI registry source
- Kustomization: applies Kustomize overlays from a source
- HelmRelease: deploys a Helm chart from a source with specified values
- ImageRepository: watches a container registry for new image tags
- ImageUpdateAutomation: automatically updates image tags in Git when new images are pushed
# Flux GitRepository
apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
name: config-repo
namespace: flux-system
spec:
interval: 1m
url: https://github.com/mycompany/config-repo
ref:
branch: main
# Flux Kustomization
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
name: api-production
namespace: flux-system
spec:
interval: 5m
sourceRef:
kind: GitRepository
name: config-repo
path: ./clusters/production/namespaces/api
prune: true
targetNamespace: api
Flux doesn't have a built-in web UI in the same way ArgoCD does. It's managed primarily via CLI (flux) and manifests. This makes it feel more "GitOps-native" to some practitioners — Flux's own configuration lives entirely in Git, managed by Flux itself.
ArgoCD vs Flux: which to choose
Both tools are mature, widely used, and maintained by strong communities. The choice usually comes down to UI preferences and composition model:
Choose ArgoCD if: your team values a visual dashboard for deployment status, you want a unified view across many clusters, or you're adopting GitOps for the first time and want a guided UI to understand what's happening.
Choose Flux if: you prefer a Kubernetes-native composable model, you want to manage Flux's own configuration via GitOps, or you need the image automation features (automatic image tag updates) that Flux provides out of the box.
Both support multi-cluster deployments, RBAC, SSO integration, Helm, and Kustomize. Both are CNCF graduated projects. Switching between them is possible but non-trivial — once a team is invested in ArgoCD's Application CRDs or Flux's source controller patterns, migrating means rewriting deployment configuration.
When GitOps makes sense
GitOps genuinely helps in these situations:
Multi-environment management. When you have dev, staging, and production environments and want changes to flow through them consistently. GitOps makes the progression explicit — a PR to update staging, review, then a PR to update production.
Regulatory compliance and audit requirements. Every change is a Git commit with an author and timestamp. Audit trails are the commit log. Change approval is the PR review process. This maps naturally to SOC 2, ISO 27001, and similar requirements.
Preventing configuration drift. Without GitOps, someone inevitably makes a kubectl change that isn't reflected anywhere, and six months later nobody knows why that resource is configured differently from what the manifests say. Continuous reconciliation closes this gap.
Large teams. When multiple teams deploy to shared clusters, GitOps provides a structured review process via PRs rather than direct cluster access. Cluster operators review and merge config changes; they don't need to trust every team to run kubectl correctly.
When GitOps adds overhead without value
GitOps isn't always the right choice:
Small teams or solo projects. A two-person team doesn't need the overhead of maintaining separate config repos and GitOps controllers. A simple CI pipeline that runs helm upgrade after merge is easier to understand and maintain.
Stateful workloads with complex upgrade procedures. Database migrations, multi-step upgrades, or operations that require ordering guarantees don't fit well into declarative reconciliation. GitOps handles stateless workloads well; it's awkward for operations that need imperative steps.
Early-stage applications with rapidly changing infrastructure. If your deployment configuration changes multiple times per day, the PR review process becomes a bottleneck. GitOps adds value when the review gate is valuable; it adds friction when fast iteration matters more.
Bootstrapping a cluster with GitOps
A common pattern: use Terraform to provision the cluster (EKS, GKE, AKS), then bootstrap GitOps with a single apply command that hands off further configuration to the GitOps controller.
# Bootstrap Flux onto a new cluster
flux bootstrap github \
--owner=mycompany \
--repository=config-repo \
--branch=main \
--path=clusters/production \
--personal=false
# After this, everything in clusters/production/ is managed by Flux
# Including Flux's own configuration
After bootstrap, even adding new namespaces, installing cluster addons (cert-manager, external-dns, ingress-nginx), or configuring RBAC happens through Git commits rather than direct cluster commands.
