In 2017, a small team at Weaveworks coined the term GitOps to describe something they had been doing internally: treating Git as the single source of truth for their entire infrastructure. What started as an internal convention has since grown into a movement with formal principles, a dedicated working group, and two of the most widely adopted continuous delivery tools in the cloud-native world. Today, when platform teams describe how they ship software, GitOps examples come up again and again, because the pattern solves a problem every operations team knows well: the gap between what is in production and what anyone thinks is in production. (What is GitOps?)
This article walks through concrete GitOps examples, from a simple single-cluster setup to multi-environment promotion flows, and explains what each one teaches. It also covers the mistakes that trip up teams in practice, because the theory is cleaner than the reality.
What Makes an Example a GitOps Example
Before looking at specific patterns, it helps to be precise about what qualifies. The GitOps working group, a Cloud Native Computing Foundation initiative, published a set of principles that define the approach. Four of them matter most:
- Declarative: the entire desired state of the system is expressed declaratively.
- Versioned and immutable: that desired state is stored in a way that enforces immutability and retains full version history, which in practice means Git.
- Pulled automatically: software agents pull the desired state from the source rather than being pushed to.
- Continuously reconciled: agents constantly observe the actual state and act to converge it toward the desired state.
Notice what is not in that list. There is no requirement for a specific tool, no mandate for Kubernetes, and no rule that a human must approve every change. A shell script that polls a Git repository and applies manifests technically satisfies the letter of the principles, though in practice almost everyone reaches for a mature tool.
The pull-based requirement is the one teams most often get wrong. A CI pipeline that runs `kubectl apply` at the end of a build is not GitOps, even if the manifests live in Git. It is Git-triggered push deployment. The distinction matters because pull-based reconciliation is what gives GitOps its self-healing property: if someone edits a resource by hand at 2 a.m., the agent notices the drift and reverts it.
Example 1: The Single-Cluster Starter Setup
The most common entry point looks like this. A team has one Kubernetes cluster and one repository containing a `manifests/` directory. Inside are plain YAML files for a Deployment, a Service, and a ConfigMap.
An Argo CD Application resource points at that repository path and target cluster. Once applied, Argo CD clones the repo, renders the manifests, compares them to live state, and syncs. The Application object itself can live in Git too, which makes the whole arrangement self-managing.
The Flux equivalent is even simpler to bootstrap. Running `flux bootstrap` commits the Flux controllers into the repository and configures them to reconcile from that same repository. From that moment, the cluster manages its own GitOps tooling.
What this example teaches: the feedback loop is the product. The first time a developer deletes a Deployment manually and watches it reappear within a minute, the mental model clicks. That single experience converts more skeptics than any architecture diagram.
A practical tip from teams running this pattern: start with a namespace you do not care about. Let the reconciler fight with you for a week. You will learn more about drift, pruning behavior, and sync policies from that sandbox than from any documentation.
Example 2: Environment Promotion Across Staging and Production
The second canonical pattern separates environments into directories or branches. A typical layout has `clusters/staging/` and `clusters/production/`, each with its own kustomization or Helm values overlay. Both are reconciled by the same controller, but to different clusters. (DevOps)
Promotion becomes a pull request. A developer changes the image tag in the staging overlay, merges, and watches staging converge. Once validated, a second pull request changes the production overlay. The Git history is the deployment history, complete with reviewer names and timestamps.
| Aspect | Directory-based promotion | Branch-based promotion |
|---|---|---|
| Review model | Standard pull request against main | Pull request into an environment branch |
| Merge conflicts | Rare, since overlays are separate files | Frequent when branches diverge |
| Audit trail | Linear, easy to read | Split across branches, harder to trace |
| Rollback | Revert one commit | Revert or reset the branch |
| Common in practice | Yes, the dominant pattern | Less common, mostly legacy |
Branch-based promotion looks tidy on a whiteboard and causes pain in practice. Long-lived environment branches drift, cherry-picking becomes routine, and the “what is actually deployed” question gets harder to answer, not easier. Directory-based overlays keep everything on one branch and make the diff between environments visible in a single view.
Example 3: Progressive Delivery With Automated Rollback
A more advanced example layers progressive delivery on top of reconciliation. The desired state in Git specifies a canary rollout: 5 percent of traffic for two minutes, then 25 percent, then 100 percent, with automated analysis at each step.
The reconciler applies the canary resources. A metrics provider feeds success rates back. If error rates exceed a threshold, the rollout aborts and traffic returns to the stable version, all without a human touching a terminal.
This is where GitOps stops being about deployment mechanics and starts being about risk. The Git commit expresses intent (“ship version 2.4.1 gradually”), and the controller decides whether that intent is safe to fully realize. Teams that adopt this pattern typically report that their mean time to recovery drops sharply, not because incidents vanish but because rollback stops being a decision made under pressure.
The mistake here is adopting progressive delivery before basic reconciliation is stable. If your syncs are flapping, adding canary analysis just gives you more moving parts to debug.
Example 4: Infrastructure Beyond Kubernetes
GitOps is often associated with containers, but the pattern extends to cloud infrastructure. A repository holds Terraform or Crossplane definitions for networks, databases, and IAM roles. A controller reconciles them on a schedule.
The nuance: Terraform’s own workflow is push-oriented by default, so teams typically wrap it in a controller that runs plan and apply on drift detection. Crossplane takes the more native route, exposing cloud resources as Kubernetes custom resources so the same reconciler handles everything.
This example is worth studying because it exposes a real tension. Infrastructure changes often carry blast radius that application changes do not. A misconfigured security group can expose a database. Many teams therefore keep infrastructure in GitOps for detection while requiring a manual approval gate for application. That is a legitimate middle ground, and pretending otherwise is how teams get burned.
Example 5: The AI Agent and Automation Layer
A newer pattern worth watching connects GitOps repositories to autonomous tooling. Instead of a human opening every pull request, an agent monitors cluster health, proposes manifest changes, and opens a pull request with a rationale attached. The human reviews and merges.
This keeps the core GitOps guarantee intact, since the agent proposes rather than applies, while removing the toil of routine updates. If you want to understand the broader category of autonomous systems that operate this way, a good primer on what is an ai agent, with examples and applications, covers the underlying mechanics of proposal-and-review loops.
The risk is obvious: an agent that can open pull requests against production manifests is an agent that can propose a bad change. Guardrails matter. Require signed commits, restrict the agent to specific paths, and never grant it merge rights.
Common Mistakes Teams Make
After enough GitOps rollouts, the failure modes start to rhyme.
Storing secrets in Git. This remains the single most common error. Base64 encoding is not encryption. Use an external secret store or a sealed-secrets mechanism, and treat any plaintext credential in repository history as compromised.
Skipping drift detection alerts. Reconciliation silently fixes drift. That looks helpful until you find out you never learned someone was editing production by hand. Alert on drift instead of only correcting it.
Over-abstracting too early. Teams with three services build a Helm chart of Helm charts wrapped in Kustomize overlays. Six months later nobody can trace a value from repository to running pod. Start with plain manifests and add abstraction when duplication actually hurts.
Ignoring repository performance. A monorepo with thousands of manifests and a one-minute reconciliation interval will hammer your Git server. Path filtering and webhook-driven reconciliation exist for a reason.
Treating the UI as the interface. Clicking sync in a dashboard is fine for debugging. If it becomes the normal workflow, you have rebuilt push deployment with extra steps and lost the audit trail that justified the whole exercise.
A Practical Starting Checklist
For teams about to build their first real example, the sequence that works most reliably is:
- Pick one non-critical service and one cluster.
- Put its manifests in a repository and reconcile them with a controller.
- Break something on purpose and confirm self-healing.
- Add a second environment as a directory overlay.
- Move secrets to an external store before onboarding anyone else.
- Add drift alerts and a dashboard showing sync status per application.
- Only then add progressive delivery.
Each step is reversible. That matters, because the teams that succeed with GitOps tend to be the ones that treated adoption as a series of small, boring, verifiable steps rather than a platform migration.
Conclusion
The GitOps examples that matter are not the most elaborate ones. A single repository, a reconciler, and a developer who trusts that the cluster will return to its declared state, that combination delivers most of the value. Environment promotion, progressive delivery, and infrastructure reconciliation are natural extensions once the loop is stable.
What ties every example together is a shift in where truth lives. Instead of a cluster that accumulated changes over years of ad-hoc commands, you get a repository that describes intent and a controller that enforces it. The tooling is interchangeable. The discipline is not.
Frequently Asked Questions
Is GitOps only for Kubernetes?
No, though Kubernetes is where it is most mature. The principles apply to any system with a declarative API and a reconciliation agent. Virtual machines, network devices, and cloud resources can all be managed this way, often through controllers that translate Git state into provider API calls.
Do I need both Argo CD and Flux?
No. They solve the same core problem and teams almost always pick one. Argo CD offers a richer built-in UI and application-centric model. Flux is more composable and leans on the native CLI. Choosing both in one cluster is possible but adds operational surface for little gain.
Is a CI pipeline that applies manifests considered GitOps?
Not by the formal definition. Pull-based reconciliation is a core requirement. A pipeline that runs apply commands at the end of a build is push deployment triggered by Git. It can be a reasonable stepping stone, but it lacks self-healing and drift correction.
How do I handle secrets in a GitOps repository?
Store them outside Git and reference them. Options include an external secret manager synced into the cluster, or encryption at rest with keys held separately from the repository. Whatever you choose, never commit plaintext credentials, and rotate anything that has ever been committed.
What happens if the Git repository goes down?
The cluster keeps running on its last reconciled state. Reconciliation pauses until connectivity returns. This is a genuine strength of the pull model: an outage in your source control does not take down production, though it does freeze your ability to deploy.
How often should reconciliation run?
Most teams settle between one and five minutes for applications, with longer intervals for infrastructure. Faster intervals catch drift sooner but increase load on the Git server and the controller. Webhook-triggered reconciliation on push is a common way to get fast deploys without a short polling interval.
