In early 2024, the company that coined the term “GitOps” shut its doors. Weaveworks, the firm that popularized the idea in 2017, wound down operations even as the pattern it championed became the default way large teams ship software to Kubernetes. That irony tells you something important: GitOps outgrew any single vendor. The architecture now lives in the CNCF ecosystem, in tools like Argo CD and Flux, and in the operating habits of platform teams worldwide.
This article breaks down how GitOps architecture actually works, where it fits, where it breaks, and what practitioners get wrong when they adopt it.
What GitOps architecture actually means
GitOps is an operating model: a Git repository holds the desired state of your infrastructure and applications, and an automated agent continuously makes the live system match that state. Git holds code and serves as the single source of truth for everything that should exist in production.
That distinction matters. In a traditional CI/CD pipeline, the pipeline pushes changes into a cluster. In GitOps, the cluster pulls its configuration from Git and reconciles itself. The direction of control flips, and that flip changes almost everything about how you reason about security, rollbacks, and drift.
The pattern sits on top of broader ideas about how systems are structured. If you want the foundational vocabulary first, it helps to understand what software architecture means as a discipline before layering GitOps on top.
The four OpenGitOps principles
The CNCF GitOps Working Group distilled the model into four principles that together define whether something is genuinely GitOps or just “we use Git”:
- Declarative. The entire desired state is expressed declaratively, not as a sequence of imperative commands.
- Versioned and immutable. That state is stored in a way that preserves full history, typically Git.
- Pulled automatically. Software agents pull the desired state from the source without external push triggers.
- Continuously reconciled. Agents constantly observe the actual state and act to converge it toward the desired state.
Miss any one of these and you have something adjacent to GitOps, not GitOps. A pipeline that runs `kubectl apply` from CI satisfies principles one and two but fails three and four. That is push-based deployment, and it is a different animal.
The two-repository model
Most mature GitOps setups separate concerns into two repositories, and this split is one of the most consequential architectural decisions you will make.
| Repository | Contents | Who touches it | Change frequency |
|---|---|---|---|
| Application repo | Source code, unit tests, Dockerfile, CI pipeline | Application developers | Very high |
| Config / deployment repo | Kubernetes manifests, Helm values, Kustomize overlays, environment definitions | Platform and ops teams | Moderate |
The application repo builds and publishes container images. The config repo declares which image version runs in which environment. When a developer merges code, CI produces an image tag, and a small automated step updates the config repo. The in-cluster agent notices the new commit and reconciles.
This separation gives you a clean audit trail. The config repo’s Git history is your deployment history. Rolling back means reverting a commit, not scrambling to remember which pipeline run broke things at 2 a.m.
Why the pull model improves security
Here is the practical payoff that sells most teams on GitOps. In a push-based pipeline, your CI system needs credentials to your production cluster. Those credentials live in a CI environment, which is a juicy target. In the pull model, the cluster reaches out to Git. The CI system never touches the cluster at all.
That means a compromised CI runner cannot silently deploy to production. The blast radius shrinks considerably. For regulated industries, this single property often justifies the migration on its own. (DevOps)
Core components of a GitOps stack
A working GitOps architecture has a handful of moving parts, and knowing each one helps you debug when reconciliation stalls.
The Git source. Usually a hosted Git provider, sometimes with branch protection rules that require review before merge. Some teams add signed commits for supply chain integrity.
The reconciliation agent. Argo CD or Flux are the two dominant options. Both run inside the cluster, watch Git, and continuously compare desired versus actual state. Both were accepted into the CNCF and later graduated, signaling production maturity.
The manifest tooling. Plain YAML, Helm charts, or Kustomize overlays. Kustomize is especially common because it lets you define a base configuration and patch it per environment without templating logic.
The image automation layer. Flux ships controllers that can watch a container registry and commit new image tags to the config repo automatically. Argo CD relies on external tooling or CI for the same job.
The observability layer. Reconciliation is only trustworthy if you can see it. Alerts on sync failures, drift detection dashboards, and health checks on the agent itself are not optional extras.
If your team is also working with AI-assisted design tooling for infrastructure diagrams or platform blueprints, it is worth reviewing the best AI architecture generators for building designs to see how generated diagrams compare with hand-maintained documentation. The same principle applies: the artifact should be versioned and reviewable, not a one-off sketch.
Push versus pull: a practical comparison
Teams often ask whether they can keep their existing pipeline and just add Git as a record. The answer is technically yes, but the tradeoffs are real.
| Dimension | Push-based | Pull-based |
|---|---|---|
| Cluster credentials in CI | Required | Not required |
| Drift detection | Manual or absent | Continuous and automatic |
| Rollback mechanism | Re-run pipeline | Revert a commit |
| Audit trail | Pipeline logs | Git history |
| Out-of-band changes | Undetected | Reconciled or flagged |
| Complexity | Lower initially | Higher initially |
The honest read: push-based is simpler to start and weaker at scale. Pull-based costs more setup effort and pays it back in operational predictability. Neither is wrong for a three-person team running a single cluster. Both matter enormously once you have twenty clusters and a compliance auditor.
Common mistakes teams make
Practitioners who have run GitOps in production tend to flag the same handful of pitfalls.
Treating Git as a backup instead of the source of truth. If engineers can still `kubectl edit` a deployment in production and nobody notices, you have not adopted GitOps. You have adopted GitOps theater. Enforce reconciliation and let the agent revert manual changes.
One giant config repo with no structure. Monorepos work, but only with clear directory conventions. Without them, environment overlays bleed into each other and a change meant for staging ships to production.
Ignoring secrets management. Plain Kubernetes Secrets in Git is a recurring and avoidable mistake. Use Sealed Secrets, External Secrets Operator, or SOPS with cloud KMS. Never commit base64-encoded credentials and call it encrypted.
Skipping the image update automation. If a human has to manually bump image tags in the config repo after every build, the process will drift. Automate the write-back.
Underestimating reconciliation lag. Agents poll on intervals. A change can take minutes to land. Teams expecting instant deploys need to tune sync intervals or accept the delay.
Forgetting the agent itself. Your GitOps controller is critical infrastructure. If it goes down, nothing reconciles. Run it with high availability, monitor it, and back up its state.
Designing for multiple environments and clusters
The architecture gets interesting at scale. A typical progression looks like this:
- Single cluster, single environment. One config repo, one Argo CD instance. Fine for early-stage teams.
- Multiple environments via overlays. A base directory plus per-environment patches. Staging and production share structure but differ in replicas, resources, and secrets.
- Multiple clusters via a management cluster. A central Argo CD or Flux instance manages many downstream clusters, each registered as a target.
- Cluster-of-clusters with tenant isolation. Platform teams provision clusters declaratively, and application teams get scoped namespaces with their own reconciliation boundaries.
Each step adds governance complexity. The jump from two to three is usually where teams need to think hard about who can merge to which overlay, because that merge permission is now effectively production deploy permission.
The permissions question nobody plans for
Here is the thing experienced operators emphasize: in GitOps, repository write access equals deployment authority. A developer who can merge to the production overlay directory can ship to production. That is a feature, not a bug, but it demands branch protection, required reviews, and CODEOWNERS files that map directories to responsible teams. Many teams migrate to GitOps and inherit their old, loose repo permissions without realizing they just handed out production keys.
How GitOps fits with platform engineering
GitOps has become a default building block for internal developer platforms. The pattern gives platform teams a uniform interface: if you want infrastructure, you open a pull request. That interface is legible to auditors, reviewable by peers, and reversible.
It also pairs naturally with declarative infrastructure tools. Terraform or Crossplane can provision the cluster and its baseline add-ons, while Argo CD or Flux handles the workloads running inside. The boundary between the two needs deliberate design, because overlapping ownership causes reconciliation fights where two controllers keep undoing each other’s work.
The practical rule: one controller owns one resource. If Terraform created it, GitOps should not also manage it. Draw that line early and document it.
Conclusion
GitOps architecture is less a product than a discipline. It asks you to express everything declaratively, store it in version control, and let software close the gap between what you wrote and what is running. The pull-based model improves security by removing cluster credentials from CI. The two-repo split gives you an audit trail that satisfies auditors and on-call engineers alike. And the continuous reconciliation loop means drift gets caught by a machine instead of by a customer.
The failures are predictable: manual edits that undermine the source of truth, secrets committed in plaintext, loose repo permissions that quietly grant production access, and controllers nobody monitors. Avoid those and the pattern delivers what it promises.
Weaveworks is gone, but the architecture it named is now standard equipment. That is probably the best evidence that the idea was bigger than the company that launched it.
Frequently asked questions
What is the difference between GitOps and CI/CD?
CI/CD is about building, testing, and delivering artifacts. GitOps is about how the desired state of a running system is stored and enforced. They complement each other: CI builds the image, and GitOps delivers the configuration change. You can run CI/CD without GitOps and GitOps without a traditional CD stage, but most mature setups use both.
Is GitOps only for Kubernetes?
No, though Kubernetes is where it took off because Kubernetes resources are natively declarative. The same principles apply to cloud infrastructure, network configuration, and even database schema management. Any system with a declarative API and a reconciliation loop can be managed this way.
Do I need Argo CD or Flux to do GitOps?
Strictly speaking, no. The principles do not name a tool. In practice, almost everyone uses one of the two major CNCF-graduated controllers, because building a reliable reconciliation agent yourself is a large project with little payoff. Some managed platforms bundle their own implementation.
How do I handle secrets in a GitOps repository?
Never commit plaintext secrets. Common approaches include encrypting values with SOPS and a cloud KMS key, using Sealed Secrets so only the cluster can decrypt, or pulling secrets at runtime from an external vault via the External Secrets Operator. The right choice depends on your cloud provider and compliance requirements. (Cloud Native Computing Foundation)
What happens if someone changes the cluster manually?
The reconciliation agent detects the difference between desired and actual state and reverts it, depending on your sync policy. Some teams configure automatic self-healing so drift is corrected within minutes. Others prefer to flag drift for review first. Either way, the manual change does not survive.
How long does a GitOps deployment take?
It depends on your sync interval and webhook configuration. Agents that poll every three minutes can take that long to notice a commit. Most teams add webhooks so the agent is notified immediately, bringing end-to-end latency down to under a minute in typical setups.
