GitOps Reverser

GitOps Reverser watches selected Kubernetes resources and commits a clean YAML representation to Git. It strips status, managedFields, and runtime metadata. For supported layouts, it updates existing manifests in place, preserving comments and document structure.

Use it to capture live changes, bring an existing cluster into Git, or experiment with API-first workflows alongside Flux or Argo CD.

Quick start: install the operator and capture your first ConfigMap in Git.

It is pre-1.0: the CRDs are v1alpha3 and the configuration surface can still change between releases. Before you adopt it covers what to weigh.

Inspect an example commit. Named Kubernetes actors in Git history require optional audit attribution; the default uses a configured Git identity.

How it works

Changes reach the Kubernetes API however your users make them: kubectl, a GUI, a CI job, or an agent over MCP.

1. Watch the Kubernetes API for the types each GitTarget claims, the single source of object state. A new target also reconciles all existing resources of those types into Git.
2. Sanitize the change and compare it against what Git already holds.
3. Write stable YAML to the target folder and push, grouping a burst of changes into one commit.

Custom resources configure it: GitProvider for repository and credentials, GitTarget for branch and folder, WatchRule or ClusterWatchRule for what to capture, and ClusterProvider for the source cluster, created as default on install. A rule selects whole resource collections, including their deletions; the GitTarget's prune mode decides whether a deletion removes the file from Git. See Configuration.

By default it watches its own cluster. Add more of each as you need them: one operator can serve several source clusters, repositories, branches, and folders.

Principles

• Creates Git commits. The only output is Git commits that reflect the state of your cluster. Deploying is Flux's and Argo CD's job: run one alongside to bring changes from Git back into the cluster. See bi-directional usage.
• API-first, not API-only. Most changes are assumed to arrive through the API, so that is what publishing is tuned for. Your changes end up in your remote Git repo within seconds. Other authors can push to the same branch, and that is handled without conflicts. If an API edit and a Git commit touch the same resource (which is rare!), then the API wins. See API-first publication for more depth.
• Authors are established, never asserted. An attributed commit names the identity the API server authenticated for the change; everything else carries the configured Git identity, or an explicit unknown when attribution is on but cannot resolve. No field lets anyone type a name in. See attribution.
• Resources classified as sensitive require encryption before commit. If encryption fails, or no encryptor is configured, the write is rejected. See SOPS and age.

Features

• Capture existing resources and future changes. A new target captures the selected resources already in the cluster, then follows changes, including deletions under a deletion policy.
• Mirror only the objects you label. A rule's objectSelector lets the API server choose which objects of a type are mirrored; an object that loses its label leaves the mirror like a deleted one. See selecting objects by label.
• In-place edits keep the shape of your file. Updates preserve key order, comments, and untouched documents in multi-document files.
• Inspect a repository before you point at it. manifest-analyzer --mode scan-repo classifies every candidate folder under a repository root, read-only and with no cluster. See cmd/manifest-analyzer/.
• SOPS and age, set up on the fly. The operator creates the encryption configuration and can generate a missing age key in your chosen Kubernetes Secret. See SOPS and age.
• Optional audit attribution identifies Kubernetes actors. Without it, commits carry the configured Git identity; when attribution cannot be resolved, they carry an explicit unknown author. See audit attribution.
• Custom commit messages. Separate templates for live windows, reconciles, and save requests. See message templates.
• SSH-signed commits. Configured through GitProvider.spec.commit.signing. See commit signing.
• kubectl wait works on every resource. Conditions follow the kstatus convention, so Ready, Reconciling, and Stalled mean what GitOps tooling expects. See status conditions.
• Metrics on a standard endpoint. Scrape /metrics with whatever you already run, or turn on the chart's ServiceMonitor. The docs carry example queries for the questions operators ask, and a named list of what is deliberately not instrumented. See interpreting metrics.

What it can write

Choose the resources to watch and the repository, branch, and folder to write into.

Your source in Git	What you can do
Plain Kubernetes manifests	Capture resources and update their existing YAML documents
Supported Kustomize layouts	Update source manifests or image/replica declarations; add and remove resources
A Flux HelmRelease or Argo CD Application	Capture the declaration, including chart versions and inline values
Helm templates or standalone values.yaml	No writeback from rendered workloads

Kustomize support includes local bases and overlays, with the base kept read-only when targeting an overlay. Generators, components, remote bases, and several other transforms are unsupported: a folder that uses them is refused with Stalled=True and a reason, while the folder is still untouched. See the supported subset.

Select the resources that express your intent. For example, watch a HelmRelease to capture chart settings. The operator cannot automatically distinguish authored resources from controller-generated ones. See choosing what to capture.

Quick start

Follow the installation walkthrough to capture ConfigMaps from a demo namespace into a disposable repository. You need a Kubernetes cluster, kubectl, Helm 3, and Git write access. The walkthrough includes cert-manager setup; Redis and audit delivery are optional.

The demo captures a live change:

kubectl create configmap test-config --from-literal=key=value -n gitops-reverser-quickstart-demo

Inspect the commit under live-cluster/ in your repository. Then edit the ConfigMap and inspect the next diff. The walkthrough includes status checks, troubleshooting, and cleanup.

Batch changes into a commit

Changes for the same target and author share a commit window, and each window becomes one commit. When a window closes is yours to tune: its timers are set per GitTarget, and a CommitRequest can bring its own timers along with the commit message. This allows the person making a change to explain why the change was necessary.

The picture shows the commit-window example running. It carries the manifests: a GitTarget with a window, a WatchRule selecting the two types, and a save request made after the changes or before them. It runs on top of the quickstart above.

Try it with your existing repo

Start with a scratch branch containing your existing manifests, with no reconciler deploying that branch. Select a small resource scope and one destination folder. Inspect the initial commits before making a live edit, then check which source files changed.

The operator pushes directly to the configured branch. If you later write to a branch that Flux or Argo CD deploys, read the bidirectional guide first. Live edits can be reverted by the reconciler, and replaying captured state can overwrite concurrent Git edits to the same object. Decide per folder which side is authoritative.

Before you adopt it

The CRDs are v1alpha3, so the configuration surface can change between releases; docs/UPGRADING.md carries each migration. Keep one GitProvider per repository, so that two of them never write the same paths.

• Access: the chart defaults to cluster-wide read access, including Secrets. Review RBAC to restrict watched types and understand the remaining credential permissions.
• History: batching can collapse intermediate edits. Unpublished work is held in memory and can be lost on restart; recovery captures current state. Git history is not a complete event log.
• Deletes: the default mirrors observed delete events but retains documents absent from a reconnect snapshot. Choose a deletion policy that fits your repository.
• Versions: tested against Kubernetes 1.37 at the API level (envtest) and 1.36 end-to-end (k3s, which has no stable 1.37 release yet). Other versions may work but are not in the matrix. Importing this repo as a Go module carries its own version floor; see docs/UPGRADING.md.

It runs one replica, with no standby failover: the chart rejects replicaCount > 1 rather than let two instances write the same repository. Ownership coordination and a durable worker queue are on the way to 1.0. The backlog is in docs/TODO.md, and longer-range directions in docs/future/.

Rather have it managed?

ConfigButler can run a small, secure, public-facing Kubernetes API for you: we operate GitOps Reverser and authorize your end users, with forward-deployed engineers to get you started. You keep a clean, self-owned Git repo where your users express their intent.

Documentation and feedback

• Configuration: resource selection, Git destinations, and commit behavior
• Helm chart: installation options and upgrades
• Documentation index: setup guides and operational details
• Reverse GitOps: the manifesto for the broader pattern

Trying it with a real repo? Open an issue with the layout you tried, the diff you expected, and what happened. Install attempts, first-commit experience, audit delivery, Git output shape, and CRD ergonomics are the most useful reports at this stage. Contributions are welcome; see CONTRIBUTING.md.

Or connect on LinkedIn: feedback, questions, and ideas are all welcome.

Licensed under Apache 2.0.