{"canonical_url":"https://engineer.company/glossary/gitops/","content_markdown":"# GitOps\n\n## What it is\n\nGitOps is a way of operating software systems in which the desired state of a\nsystem is written down as declarations in Git, and software agents keep the\nrunning system in line with them. Nobody changes production by hand or from a\nscript on a laptop. A change is a commit, and an agent inside the environment\nnotices the new commit and makes the system match it. The OpenGitOps project\nspells the idea out as four principles, and version 1.0.0 of those principles\nwas published on 8 October 2021 by the GitOps Working Group that oversees the\nproject.\n\nThe principles say the desired state must be declarative, versioned and\nimmutable, pulled automatically and continuously reconciled. Declarative means\nthe files describe what the system should look like, not the commands that get\nit there. Versioned and immutable means a stored version is never edited, only\nsuperseded, and the complete history is kept. Pulled automatically means\nsoftware agents fetch the declarations from the source themselves. Continuously\nreconciled means agents repeatedly compare the running system with its\ndeclaration and work to bring the two together; the project's glossary adds that\ncontinuous means the work keeps happening, not that it is instantaneous.\n\nTwo boundaries in that glossary are easy to miss. Git, from which the name\ncomes, is the canonical state store, but any store qualifies that keeps\nimmutable versions and provides access control and auditing on changes to the\ndesired state. And the desired state is the configuration needed to recreate the\nsystem, which generally excludes persistent data such as the contents of a\ndatabase. GitOps can rebuild the machines a database runs on; it cannot rebuild\nthe rows inside it.\n\n## Why it matters\n\nThe difference from an ordinary deployment pipeline is what starts the work. The\nOpenGitOps glossary contrasts CI/CD jobs started by previously configured\ntriggers, with GitOps, where reconciliation is triggered whenever the actual\nstate diverges from the declared one. That divergence can come from either side:\na new commit changes what is wanted, or the running system drifts away from what\nwas declared. A pipeline that ran `kubectl apply` once has no view of what\nhappened afterwards. Kubernetes' own documentation notes that declarative apply\nkeeps writes made directly to live objects without merging them back into the\nconfiguration files, so the files and the cluster can quietly disagree. An agent\nthat reconciles notices both kinds of divergence.\n\nThe second gain is where access lives. Argo CD's documentation points out that\nwith automated sync, a deployment pipeline can work without credentials for Argo\nCD's API server: the pipeline makes a commit and pushes it. What the pipeline\nneeds is write access to a repository rather than to the cluster, and the\nrepository is where changes are reviewed anyway.\n\nThe third is the history. Because the desired state is versioned and immutable,\nthe log of the repository is a record of every intended change: what changed,\nwho changed it and when. Going back means choosing an earlier version, and Argo\nCD lists rollback to any application configuration committed in Git among its\nfeatures. After an incident, that history answers the first question, what\nchanged, without anyone reconstructing it from shell history and memory.\n\n## What it looks like in practice\n\nFlux and Argo CD are two agents that put this into practice on Kubernetes. Argo\nCD describes itself as a declarative, GitOps continuous delivery tool for\nKubernetes; Flux calls its set of controllers and APIs the GitOps Toolkit. Take\na team that keeps its production manifests in a repository called fleet. Two\nFlux objects connect the cluster to it: the first tells Flux's source controller\nwhere the repository is and how often to fetch it, and the second tells the\nkustomize controller which directory to apply and how often to check the cluster\nagainst it.\n\n```yaml\napiVersion: source.toolkit.fluxcd.io/v1\nkind: GitRepository\nmetadata:\n  name: fleet\n  namespace: flux-system\nspec:\n  interval: 5m\n  url: https://git.example.com/platform/fleet.git\n  ref:\n    branch: main\n---\napiVersion: kustomize.toolkit.fluxcd.io/v1\nkind: Kustomization\nmetadata:\n  name: production\n  namespace: flux-system\nspec:\n  interval: 10m\n  sourceRef:\n    kind: GitRepository\n    name: fleet\n  path: \"./production\"\n  prune: true\n  timeout: 1m\n```\n\nNow follow one change. An engineer merges a pull request that moves a service to\na new image tag. The source controller fetches the branch every five minutes,\nand at its next fetch it sees a new revision. A new source revision is handled\nat once rather than at the next interval, so the kustomize controller builds the\nmanifests under `./production` and applies them. Flux's documentation describes\nthe rest for exactly this pair of objects. Every ten minutes, as the interval\nsets, the `Kustomization` uses a dry run of server-side apply to discover\ndivergence, then reconciles it, so a colleague who changes the same object with\n`kubectl edit` sees the change undone. Because `prune` is on, an object whose\nmanifest has been removed from the directory is deleted from the cluster with\nthe next revision. Rolling back is a `git revert` and a merge, which travels the\nsame path as any other change.\n\nArgo CD does the same job through an `Application` resource, with different\ndefaults. One page of its documentation says it polls repositories every three\nminutes; another, on automated sync, puts the interval at 120 seconds plus up to\n60 seconds of jitter, for a maximum of three minutes. When the live state\ndiffers from the target state in Git, the application is marked OutOfSync, and\nwith automated sync on, Argo CD syncs it. By default, though, automated sync\ndeletes nothing that has disappeared from Git and does not react to changes made\ndirectly in the cluster. Pruning and self-healing are separate switches, `prune`\nand `selfHeal`, and both start off.\n\nThe same pattern works outside Kubernetes. A\n[20-record DNS zone reconciled against the provider's API](/portfolio/reconciled-a-20-record-dns-zone-as-code/),\ncarried out in August 2026, turned records that lived in a provider's web\nconsole into a declaration in the repository. One entry point reconciles the\ndeclaration against the provider; another, behind an explicit opt-in, only\naudits, reporting the difference without changing anything. The page names the\naudit as the part used most, because knowing the difference is more often what\nis wanted than closing it. Measured against the four principles, that is the\nfirst two: the zone is declared and versioned. The page does not describe an\nagent fetching the declaration and applying it on its own, so the last two are\nnot claimed. It is also a fair argument for starting where Argo CD starts by\ndefault: show the drift before letting anything correct it.\n\n## Where it goes wrong\n\n**Secrets in plain text in Git.** A repository that holds the whole desired\nstate tempts people to put the passwords there too, and its history keeps them\nafter they are deleted. Flux's documentation calls storing Kubernetes secrets in\nGit as plain text or base64 unsafe, even in a private repository with restricted\naccess. Encrypt them before they are committed. Flux decrypts with SOPS, using\nage, OpenPGP or a cloud key management service, configured through\n`.spec.decryption`; encrypt only the `data` and `stringData` fields, because\n`metadata`, `kind` and `apiVersion` must stay readable. Argo CD's documentation\nstrongly recommends a different route: resolve secrets on the destination\ncluster with a tool such as Sealed Secrets, the External Secrets Operator or the\nSecrets Store CSI Driver, rather than injecting them while Argo CD generates\nmanifests, which it cautions against partly because its Redis cache holds an\nunencrypted copy of the resulting manifests.\n\n**A hotfix that will not stay, or drift that never goes.** The two tools behave\ndifferently here by default. Under Flux, a change made with `kubectl edit`,\n`patch` or `delete` is promptly reverted, which is right until someone applies\nan urgent fix by hand during an outage and watches it disappear. Under Argo CD,\na change made directly in the cluster does not trigger an automated sync unless\nself-healing is on, so drift can sit there, marked OutOfSync, indefinitely. The\nfix is the same for both: make the change in Git, or pause reconciliation\nopenly. Flux's `.spec.suspend` stops new revisions from being applied and pauses\ndrift correction until it is set back to false. For a field another controller\nowns, such as the replica count of a `Deployment` that an autoscaler manages,\nFlux's `.spec.ignore` takes JSON Pointer paths like `/spec/replicas`, so the two\ncontrollers stop overwriting each other. Roll back through Git as well: Argo CD\nrefuses a rollback on an application with automated sync enabled.\n\n**Deleted in Git, still running.** Removing a manifest removes the declaration,\nnot the object. Argo CD's automated sync does not delete resources that are no\nlonger defined in Git unless pruning is enabled, and Flux deletes them only when\n`.spec.prune`, a field every `Kustomization` must set, is true. Leave it off and\nthe cluster slowly fills with objects that nobody declares. Turn it on, and mark\nthe few objects that must outlive their manifest with the\n`kustomize.toolkit.fluxcd.io/prune: disabled` label or annotation. Argo CD adds\na guard worth keeping: automated sync with pruning will not leave an application\nwith no resources at all unless `allowEmpty` is set, which stops a broken commit\nthat empties a directory from emptying the cluster.\n\n**A merge that waits for the poll.** An agent that fetches on a timer trades\nspeed for independence: Argo CD gives three minutes as its polling period, and\nFlux sees a commit at the next fetch of the source. Both accept a webhook from\nthe Git server to cut the wait. Argo CD takes it at its `/api/webhook` endpoint;\nFlux uses a `Receiver` resource that turns a push event into a reconciliation of\nthe sources it lists. Argo CD's shared webhook secret is optional, because a\npayload only triggers a refresh, but its documentation recommends one when Argo\nCD is publicly reachable, to prevent distributed denial-of-service attacks. Flux\ngenerates a unique webhook path from the receiver's name, namespace and a secret\ntoken and, for GitHub, verifies the payload's HMAC signature.\n\n**Git becomes a production dependency.** If the agent fetches from the Git\nserver, a Git outage stops every change, fixes included. Flux's OCI-based\nvariant, which it calls Gitless GitOps, keeps Git as the interface people use\nbut has the cluster pull versioned artifacts from a container registry, allowing\nthe cluster to obtain its production artifacts without contacting the Git\nserver. Whichever source the agent reads, give it the availability you expect of\nproduction, because during an outage it is the only route a change can take.\n\n## Further reading\n\n- [OpenGitOps](https://opengitops.dev/) — the four GitOps principles, version\n  1.0.0, from the GitOps Working Group.\n- [GitOps Glossary v1.0.0](https://github.com/open-gitops/documents/blob/v1.0.0/GLOSSARY.md)\n  — the definitions behind the principles: desired state, drift, reconciliation\n  and the state store.\n- [Automated Sync Policy](https://argo-cd.readthedocs.io/en/stable/user-guide/auto_sync/)\n  — Argo CD's automated sync, with the prune, self-heal and allow-empty switches\n  and when each sync runs.\n- [Kustomization](https://fluxcd.io/flux/components/kustomize/kustomizations/) —\n  Flux's API for applying a directory of manifests: interval, prune, suspend,\n  ignore and SOPS decryption.\n- [Secret Management](https://argo-cd.readthedocs.io/en/stable/operator-manual/secret-management/)\n  — Argo CD's case for resolving secrets on the destination cluster rather than\n  during manifest generation.\n- [Declarative Management of Kubernetes Objects Using Configuration Files](https://kubernetes.io/docs/tasks/manage-kubernetes-objects/declarative-config/)\n  — how `kubectl apply` and `kubectl diff` work on a directory of configuration\n  files, and what apply does with changes made to live objects.\n\n\u003chttps://engineer.company/glossary/gitops/\u003e\n","date_modified":"2026-10-30T02:51:31Z","description":"How GitOps runs infrastructure from a desired state kept in Git, how Flux and Argo CD reconcile it, and where it goes wrong.","formats":{"gemtext":"https://engineer.company/glossary/gitops/index.gmi","gopher":"https://engineer.company/glossary/gitops/gophermap","html":"https://engineer.company/glossary/gitops/","json":"https://engineer.company/glossary/gitops/index.json","markdown":"https://engineer.company/glossary/gitops/index.md","pdf":"https://engineer.company/glossary/gitops/index.pdf"},"kind":"page","language":"en","title":"What is GitOps?","url":"https://engineer.company/glossary/gitops/","version":1}