FAQ

What is Reverse GitOps?#

Reverse GitOps is an API-first operating model. Instead of asking users to push YAML to Git directly, they express intent through a typed platform API: Kubernetes custom resources. A controller then writes that validated intent back into Git as a commit or pull request. The standard GitOps delivery pipeline (review, promotion, auditability) stays fully intact downstream.

API-first does not mean API-only. Teams can still make changes in Git when that is the right interface. The point is that Git no longer has to be the only user-facing write path.

Why not just use Git directly?#

Git is excellent for review, history, promotion, and distribution. It is often much less good as the primary interface for every human or tool that wants to make a small change. Platform teams frequently end up building an API or UI on top of Git workflows anyway.

Reverse GitOps makes that API a first-class part of the design. Users express intent through a typed Kubernetes API, and a controller writes the resulting change back to Git for review and delivery. Git remains available for direct changes too; Reverse GitOps just stops treating Git as the only acceptable interface for writing intent.

Is Reverse GitOps trying to replace GitOps?#

No. It changes where intent enters the system, not the delivery model. Git can still be where changes are reviewed, promoted, audited, and distributed to target environments through GitOps operators such as Flux or Argo CD.

In practice, that also means teams can still make changes directly in Git. Reverse GitOps is API-first, not API-only.

Is Git still the source of truth?#

It depends on which question you are asking.

For user intent, the typed API is the preferred front door. For reviewable and promotable desired state, Git is still the durable system of record. Reverse GitOps does not treat the workload cluster as the place where uncontrolled edits happen. It treats the API as a first-class input surface and Git as the reviewed record that downstream GitOps operators consume, whether a change started from the API or directly in Git.

If Git and the API drift, the implementation needs to make that visible and predictable rather than silently allowing both to evolve independently.

Which cluster am I actually talking to?#

In the model described by this site, you are talking to a separate intent cluster. It is a small control plane for expressing and validating intent, not the same thing as the workload clusters where applications and infrastructure eventually run.

That separation is deliberate. It keeps the user-facing API stable, avoids giving broad access to implementation clusters, and makes it much clearer where intent is submitted, where it is recorded, and where GitOps operators take over.

Does this mean users get access to the production cluster?#

No. The pattern is about putting a small, focused control plane in front of Git. That control plane does not need to be the production workload cluster. In practice, separating them is often part of the point.

What Kubernetes primitives does this require?#

Three things: a CRD that models user intent (for example anApplication or Environment resource), a controller that watches those CRDs and opens pull requests or commits to a Git repository, and a GitOps operator downstream (Argo CD, Flux) that deploys from that repository.

The gitops-reverser project provides an open-source controller you can start from.

Can you walk me through a concrete example?#

A developer wants to deploy a new application. Instead of opening a pull request with a handwritten YAML file, they apply an Application resource to the intent cluster:

apiVersion: platform.example.com/v1
kind: Application
metadata:
  name: checkout-service
  namespace: team-payments
spec:
  image: registry.example.com/checkout:v1.4.2
  replicas: 3
  environment: production

The API server validates it immediately. Wrong field names, unknown environments, and policy violations are all caught at write time, before anything touches Git.

A controller watches the resource and opens a pull request in the GitOps repository with a clean manifest. A reviewer approves it. Flux or Argo CD picks it up and deploys the application to the target cluster. The developer can see whether their intent landed by inspecting the resource they submitted.

From the developer's perspective: one API call, immediate validation feedback, and a normal Git review process for anything that needs it. They never had to author or maintain a commit themselves.

Does this only apply to infrastructure, or to application configuration too?#

Application configuration works just as well. Nothing in the pattern is specific to infrastructure. A custom resource is a schema plus a file, and feature flags, business rules, pricing tiers, and domain settings fit that shape as naturally as aDeployment does. The Kubernetes API does not care whether the thing being described is a workload or the behaviour of a product.

That matters because application teams keep rebuilding the same machinery for their own settings: a schema, validation, permissions, an audit trail, and some way to notice that a value changed. Modelling that configuration as custom resources lets the API server do that work instead, so the team can offload a meaningful part of the responsibility for configuring their application rather than maintaining yet another admin screen backed by a bespoke database table.

It also opens up a question worth asking out loud: why not let customers work against the Kubernetes API directly? Not the production workload cluster, but a small, dedicated API that models the settings they are allowed to change. They get typed validation, resource-level authorization, and immediate feedback, while every accepted change still lands in Git as a reviewable, attributable commit. The people changing the settings never have to see Git, and the team responsible for the application still gets the history.

When should I use this pattern?#

When you want a typed, validated, RBAC-enforced API as the interface for platform users, but still need Git review, auditability, and promotion pipelines. It is a good fit for platform teams who would otherwise build a custom API or UI on top of their GitOps workflow. Reverse GitOps lets the Kubernetes API server do that work instead.

Isn't this bullshit?#

Fair question. It would absolutely be bullshit to claim that Reverse GitOps can take an existing GitOps setup built around Helm releases, elaborate Kustomize overlays, and layers of environment-specific patches, and somehow reverse that back into clean API intent. That is not what this is.

The pattern works when you have a typed, flat API resource that represents user intent cleanly. A Crossplane PostgreSQLInstance claim or a KROResourceGroup is a good fit: the user writes one clean resource, the platform handles the complexity underneath. A tangle of Helm values files with conditional templating is not.

Reverse GitOps is a model for designing new platform APIs, not a tool for reverse-engineering existing ones.

How do I debug this on day 2?#

You need to be able to trace the full path clearly: the intent submitted through the API, the Git commit or pull request that captured it, the promotion path between environments, and the resulting resources deployed by the GitOps system.

If that trace is not easy to follow, the implementation is not good enough yet. Updates, deletions, and drift handling still require explicit ownership decisions, but the debugging path should be obvious long before those edge cases show up.

How do I know whether my intent landed?#

Every user-facing resource should expose a way to answer: did my intent land, where did it land, and is it healthy there?

It should not simply mirror every implementation detail from downstream systems back into the user-facing API. At a minimum, it should make clear whether the resource has been picked up and deployed by GitOps, and it should always provide a clue about where to look next for more information.

Who is behind this?#

Right now: Simon Koudijs, consultant, trainer, and founder of ConfigButler.

But the concept is intentionally bigger than one company. The manifesto is open source, the implementations are open source, and the hope is that others will build on this, challenge it, and create their own implementations. If Reverse GitOps is a useful idea, it should not belong to anyone.

Is there an open-source implementation?#

Yes. See the Implementations page for known open-source projects. The reference implementation isgitops-reverserby ConfigButler.