docs(gitops): two source-of-truth modes design (K2)#152
Merged
Conversation
Add docs/gitops-modes.md — the prescribed first step of K2: fix the invariants for collapsing the overlapping git-as-sink + git-as-source machinery into two explicit, non-overlapping modes before touching code. - mirror (default): SQLite is truth, git is a read-only audit mirror (materialize + auto-commit + push + startup-revive; no pull/prune/webhook). - gitops: the repo is truth (pull/apply/prune/webhook + local file→apply; NO auto-commit of desired specs, NO startup file-revival). Fixes the two known conflicts (startup re-materialize vs prune; --ff-only pull vs auto-commit) via the invariants, defines the `manifests.mode` switch + contradictory-combo rejection, back-compat (default mirror), a per-component code-reconciliation checklist, and a test plan. Notes the drift reconciler is mode-agnostic and prune trusts K3's source column. The code reconciliation is a separate follow-up (tracked), best paired with homelab validation of both modes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
K2 — GitOps two-mode design (first step)
The roadmap's K2 says: "Write the invariants down first (short design doc), then reconcile the code to them." This is that doc —
docs/gitops-modes.md. No code change; it de-risks the eventual reconciliation of the metal-critical reconcile/mirror paths.The problem
git-as-source (B1–B3: pull/prune/webhook) was layered on git-as-sink (disk mirror + auto-commit + push), and the two can both be on and conflict:
--ff-onlypull fights auto-commit — a local auto-commit diverges history so the next pull fails.The design
Two explicit, non-overlapping modes, one switch (
manifests.mode: mirror|gitops), only the chosen mode's machinery runs:Both conflicts are resolved by the invariants (gitops: no auto-commit, no startup-revive). Prune's safety now rests on K3's durable
sourcecolumn (shipped), not the GC-able ops table.The doc also specifies the config surface + contradictory-combo rejection, back-compat (default
mirror, existingmanifests.git-only configs unchanged), a per-component code-reconciliation checklist, and a test plan (incl. asserting both conflicts can't occur).Follow-up (tracked in ROADMAP)
The code reconciliation itself — best paired with real homelab validation of both modes. The open "which mode is the recommended default" question ties to K5 (scope), but the mechanism here is independent of that call.
Docs only — no Go changes.