GitOps is a way of running systems where the desired state lives in Git and software inside the cluster keeps reality matching it.

GitOps is an operating model for infrastructure and applications. You describe everything you want, such as which applications run, in which versions, with which settings, in plain text files stored in a Git repository. A software agent running next to your cluster reads those files and makes the cluster match them. If someone changes the cluster by hand, the agent notices and puts it back. If you want to change the cluster, you do not touch it directly; you change the files in Git, and the agent does the rest.

The name joins two words: Git, the version control tool that records every change to a set of files, and Ops, short for operations, the daily work of running systems. The term was popularized in 2017 by engineers at Weaveworks, who used it to describe how they ran their own Kubernetes platform. Since then it has grown into a community standard, with a shared set of principles maintained by the OpenGitOps working group under the Cloud Native Computing Foundation.

It is worth noticing that GitOps is a way of working, not a product you buy. You can practice it with different tools, in different clouds, on different kinds of clusters. What makes something GitOps is not the tool but the rules it follows, and those rules are the subject of this guide.

Before GitOps, most teams shipped to Kubernetes with scripts and pipelines that had hidden weaknesses.

In a traditional setup, a continuous integration server builds your application, and then, as the last step, it runs commands to deploy to the cluster. This looks simple, but it creates several quiet problems. The pipeline needs powerful credentials to the cluster, so those credentials are stored in a build system that many people can reach. The pipeline only acts when it runs; between runs, anyone can change the cluster by hand and nobody will know. And the real state of the cluster is a mystery that must be discovered by asking the cluster, because no document reliably says what should be there.

A short refresher on the ideas GitOps builds on.

Kubernetes Is Already Declarative

Kubernetes is built around declaring a desired state. You tell it “I want three copies of this application” and its controllers work to make that true. GitOps takes that same idea one step further: it asks where the declarations themselves should live and who should be allowed to change them. The answer is Git, with reviews and history, and an in-cluster agent that applies them. In a sense, GitOps is the natural partner of Kubernetes, because both are based on the same love of declared intent and continuous correction.

It also helps to separate two kinds of software. Continuous integration is about building and testing code and producing artifacts such as container images. Continuous delivery is about getting those artifacts safely into running environments. GitOps is a particular, disciplined way of doing the delivery half. Your build server still builds; it simply stops reaching into the cluster.

The OpenGitOps standard describes four rules. A system is GitOps only if it follows all four.

flowchart LR
    A[1 Declarative description] --> B[2 Stored in Git with history]
    B --> C[3 Agent pulls automatically]
    C --> D[4 Agent reconciles continuously]
    D -->|drift detected| C
        

Each principle supports the others. Declarative files are what make versioning meaningful, because you can compare two versions and see exactly what changed. Versioning is what makes pull safe, because the agent always fetches a known, reviewed state. Pull is what makes continuous reconciliation possible, because the agent lives inside the environment and can check as often as needed. And reconciliation is what makes the declarations truthful, because the live system is forced to match them.

Say what you want, not how to get there.

A declarative description states the end result. For example, “this namespace contains an application at version two with three replicas and a public address”. An imperative description lists commands: “create a namespace, then start a container, then scale it, then expose it”. The imperative way depends on the starting point. If you run the same commands twice, or on a cluster that already has some of the pieces, you may get errors or a different result. The declarative way does not care about the starting point, because the agent simply works out the difference between what exists and what you described.

What Counts as Desired State

In Kubernetes, desired state is usually a set of manifests, but it can take other forms that eventually produce manifests. Teams use templating tools such as Helm charts, or overlay tools such as Kustomize, to avoid repeating the same text for different environments. What matters is that the final result is fully determined by files in the repository. If rendering a template pulls in values from a random web service at deploy time, the declaration is no longer fully in Git, and the principle is weakened.

Everything as Code

The same idea extends beyond application manifests. Namespaces, access rules, network policies, quotas, and even the definitions of the clusters themselves can be written as declarations. Teams that go all the way, sometimes called “everything as code”, gain the ability to recreate an entire platform from scratch simply by pointing a fresh agent at the repository.

Every change is recorded, reviewable, and reversible.

Git stores a permanent chain of commits. Each commit is identified by a unique fingerprint derived from its contents, which means history cannot be quietly rewritten without everyone noticing. This is the immutable part: once a state is recorded, it stays recorded. The versioned part means you can go back to any earlier state at any time. Together they give you an audit trail and a time machine in one.

Immutable Artifacts, Too

Immutability applies to what the manifests point at, not just the manifests. If a manifest says “use the image tagged latest”, then the same commit can mean different things on different days, because the tag can be moved to a different image. To keep the history honest, manifests should reference images by a fixed version tag or, even better, by the image’s content fingerprint called a digest. Then a given commit always means exactly one thing.

The cluster reaches out to Git. Nobody reaches into the cluster.

In a push model, an external system, such as a build server, connects to the cluster and applies changes. In a pull model, an agent running inside or beside the cluster connects outward to the repository and fetches the desired state. This small change in direction has large effects, especially for security.

flowchart TD
    subgraph PUSH [Push model]
        P1[Developer] --> P2[CI server holds cluster credentials]
        P2 -->|pushes changes in| P3[Cluster]
    end
    subgraph PULL [Pull model]
        L1[Developer] --> L2[Git repository]
        L4[Agent inside cluster] -->|pulls from| L2
        L4 -->|applies to| L3[Cluster]
    end
        

The pull model is also friendlier to firewalls and private networks. A cluster in a locked-down environment can still make outbound connections to a repository, while it may be very difficult to allow inbound connections from a build server. For organizations running dozens of clusters in different places, the pull model scales naturally because each cluster looks after itself.

The agent never stops checking, so drift cannot hide.

Reconciliation is the loop at the heart of GitOps. The agent observes what is running in the cluster, compares it with the desired state from Git, and, if they differ, takes action to bring the cluster back to the declared state. Then it does this again, forever. The loop is the same idea that powers Kubernetes controllers, applied at the level of the whole environment.

sequenceDiagram
    participant G as Git Repository
    participant A as GitOps Agent
    participant K as Kubernetes API
    loop Every few minutes or on notification
        A->>G: Fetch latest desired state
        A->>K: Read live state
        A->>A: Compare desired and live
        alt Difference found
            A->>K: Apply changes to match Git
            A->>A: Record result and health
        else Same
            A->>A: Mark as in sync
        end
    end
        

Drift: The Silent Enemy

Drift means the live system no longer matches the declared state. It happens when someone edits a resource by hand, when another automated tool changes a field, or when a resource is deleted by accident. Without reconciliation, drift accumulates unseen until it causes an outage or a failed audit. With reconciliation, drift is either undone automatically or at least reported clearly as “out of sync”.

Automatic Healing or Alert Only

Teams can choose how aggressively the agent reacts. In a fully automatic mode, the agent corrects any drift immediately, which is ideal for production consistency. In a cautious mode, the agent only reports differences and waits for a human to decide, which can be useful while a team is learning. Many teams start cautious in a few environments and move to automatic healing as confidence grows.

A GitOps setup has a handful of cooperating parts.

flowchart TD
    DEV[Developer] -->|opens pull request| APPREPO[Application source repository]
    APPREPO --> CI[CI pipeline builds and tests]
    CI -->|pushes image| REG[(Container registry)]
    CI -->|updates version in| CFG[Configuration repository]
    CFG --> AGENT[GitOps agent in cluster]
    REG --> AGENT
    AGENT -->|applies| CLUSTER[Kubernetes cluster]
    AGENT -->|reports status| DASH[Dashboard and alerts]
        

Two mature, community-driven tools dominate GitOps on Kubernetes.

Argo CD and Flux are both graduated projects of the Cloud Native Computing Foundation. Both implement the four principles. Both run inside the cluster, pull from Git or from packaged artifact stores, render manifests, and reconcile continuously. They differ in style and user experience.

Supporting Tools

How you organize Git decides how pleasant GitOps will be for the next five years.

Separate Code from Configuration

A widely recommended practice is to keep application source code and deployment configuration in different repositories. The reasons are practical. Code changes often, in small steps, and many developers touch it. Configuration changes represent deliberate decisions about what runs where, and they have a different audience and approval needs. Separating them also stops a build from triggering itself in a loop: if the pipeline commits a new version number into the same repository that triggers the pipeline, you can create an endless cycle.

One Repository or Many

Environments: Folders Beat Branches

Teams often ask whether to represent environments such as development, staging, and production as branches or as folders. Folders are generally preferred. With branches, the environments drift apart in confusing ways, merges become complicated, and it is hard to see differences at a glance. With folders on one main branch, each environment has its own directory, built from a shared base plus small overrides. Differences are easy to see, and promotion is as simple as changing a version number in the next folder.

Let us follow one change, from a developer’s idea to a running update.

stateDiagram-v2
    [*] --> OutOfSync: New commit in Git
    OutOfSync --> Syncing: Agent starts applying
    Syncing --> Synced: Cluster matches Git
    Synced --> Healthy: Workloads pass health checks
    Syncing --> Failed: Apply error
    Failed --> OutOfSync: Fix committed
    Healthy --> OutOfSync: Drift or new commit
        

Notice that synced and healthy are two different ideas. Synced means the cluster matches Git. Healthy means the things that were applied are actually working. An application can be perfectly synced to a broken configuration, which is why health checks and progressive delivery are important companions to GitOps.

Moving a release from testing to production should be boring, visible, and repeatable.

In GitOps, promotion means changing the desired state of the next environment so that it matches the version already proven in the previous one. Because both are just files in Git, promotion becomes a small, reviewable change. The same artifact that passed testing is the one that reaches production; nothing is rebuilt along the way. This guarantees that what you tested is what you ship.

Rolling Back

Rollback in GitOps is delightfully simple: revert the commit that introduced the problem. The agent sees the new desired state and restores the earlier version. Because the revert is itself a commit, the history clearly shows that a problem occurred and was undone, which is valuable for later review. Remember that rollback only restores the declared state; it cannot undo irreversible changes such as data migrations, so those need separate care.

Git must never contain plain-text passwords, yet the cluster needs them. Here is how teams reconcile the two.

Because Git is the source of truth and is widely readable, storing secrets in it as plain text would be a serious security failure. Even a private repository leaks through copies, backups, and former employees. GitOps teams use one of two broad approaches to solve this.

GitOps decides what should run. These companions help decide how safely it gets there.

Progressive Delivery

Progressive delivery is the practice of releasing a new version to a small slice of traffic first, measuring how it behaves, and only then widening the rollout. In a canary release, a small percentage of users see the new version while the rest stay on the old one. In a blue-green release, a full copy of the new version runs beside the old one, and traffic is switched over once it looks healthy. Specialized controllers can automate the analysis, using metrics such as error rate and latency, and roll back automatically if results look bad. GitOps provides the desired state, and the progressive delivery controller handles the careful transition.

Policy as Code

Policy as code means writing your organization’s rules as machine-checkable definitions. Examples include “no container may run as the root user”, “every workload must declare resource limits”, and “images must come from the approved registry”. These rules can be checked at two moments. Before merge, a pipeline validates the proposed manifests and blocks the pull request if it violates policy. At admission, the cluster itself rejects any object that breaks policy, even if it somehow got past the first check. Using both gives defence in depth.

GitOps shines brightest when you have many clusters to keep consistent.

Organizations rarely stop at one cluster. They have clusters per environment, per region, per business unit, or per customer. Managing these by hand is a recipe for drift. With GitOps, each cluster runs an agent, or a central agent manages several, and every cluster is simply a list of what it should contain. Adding a new cluster means pointing a fresh agent at the repository; within minutes, it installs everything it should have.

flowchart TD
    REPO[Central configuration repository] --> A1[Agent in cluster Dev]
    REPO --> A2[Agent in cluster Staging]
    REPO --> A3[Agent in cluster Prod Region 1]
    REPO --> A4[Agent in cluster Prod Region 2]
    A1 --> C1[Dev cluster]
    A2 --> C2[Staging cluster]
    A3 --> C3[Prod Region 1 cluster]
    A4 --> C4[Prod Region 2 cluster]
        

Fleet Patterns

GitOps improves security in many ways, but it also moves the crown jewels into Git. Protect them accordingly.

With GitOps, access to the main branch of the configuration repository is effectively access to production. That makes the repository and its approval rules a primary security boundary. At the same time, the pull model improves the security posture by removing cluster credentials from external systems and by shrinking the number of people who need direct cluster access to almost none.

A GitOps system that fails silently is worse than none, because everyone assumes Git is being obeyed.

The agent is itself a critical piece of infrastructure. If it stops working, the cluster quietly stops following Git, yet nobody may notice until something goes wrong. For this reason, teams monitor both the agent and the applications it manages.

Notifications That Matter

Connect the agent to chat and incident tools so that failures reach people quickly. Useful alerts include failed syncs, applications that remain out of sync beyond a set time, health degradations right after a rollout, and agent downtime. Because every change is a commit, you can also link deployment events back to the exact pull request and author, which makes investigating incidents much faster.

GitOps is powerful, yet it asks for discipline and brings its own costs.

GitOps Compared with Other Approaches

Organizations of all sizes use the same handful of GitOps patterns.

A Typical Adoption Journey

Habits that keep GitOps smooth, and traps that make it painful.

Handling Resources Managed by Other Controllers

Some fields in a live resource are legitimately changed by other controllers. For example, an autoscaler adjusts replica counts, and a service mesh may inject extra containers. If the agent insists that every field match Git, it will fight with these controllers. Good practice is to tell the agent which fields to ignore, or to leave those fields out of the declaration, so each actor has clear ownership.

No. The ideas apply to any system that can be described declaratively and reconciled by an agent. Kubernetes is the most common home because its controllers are built for exactly this model, but the same pattern is used for cloud resources and other platforms.

No. Continuous integration still builds, tests, and packages your software. GitOps replaces the final step of pushing into the cluster with a pull-based, reconciled delivery.

The cluster keeps running whatever it already has. The agent simply cannot see new changes until Git returns. Because the running workloads do not depend on Git, an outage there delays changes but does not stop applications.

Workloads continue to run, but drift will not be corrected and new changes will not be applied. That is why the agent should be monitored, run with high availability where possible, and covered by alerts.

Yes for anything that should persist. Pull requests give review, history, and accountability. For true emergencies, define a controlled break-glass process and bring Git back in line immediately afterwards.

Infrastructure as code is the idea of writing infrastructure in files. GitOps adds specific rules on top: the files live in version control, an agent pulls them automatically, and reconciliation continues forever. You can have infrastructure as code without GitOps, but not GitOps without it.

Typically every few minutes by default, and many setups add notifications from the Git platform so that changes are applied within seconds. The interval is a balance between speed and load.

Yes, read-only access is common and helpful for troubleshooting. What GitOps discourages is making changes there. Dashboards and read-only roles give visibility without risking drift.

Treat them as part of the release process, not as ad-hoc commands. Many teams run migrations through a controlled job triggered as part of a rollout, with careful ordering and backward-compatible changes so rollback remains safe.

Either Argo CD or Flux is a solid choice. Beginners often find a visual dashboard helpful for learning, while others like the lightweight, command-line-first style. Try both on a small cluster and keep the one that feels natural to your team.

GitOps brings the best habits of software development, review, history, and automation, to the running of systems. You declare what you want in Git, an agent inside the cluster pulls it, and a continuous loop keeps reality matching the declaration. The result is a platform where changes are visible, reversible, and accountable, and where the question “what is running in production?” can be answered by reading a repository.

To succeed with GitOps, treat it as a discipline rather than a tool installation. Design your repositories carefully, protect the main branch as you would a production control panel, handle secrets with proper tooling, promote the same artifact through every environment, and monitor the agent itself. Start small, grow with confidence, and let Git become the calm center of how your team delivers software.