tiny-forge/plans/gitops/PLAN.md

Tinyforge GitOps v1 — config-as-code for repo-backed workloads

Status: ✅ Complete (squash-merged to main 2026-06-21) Branch: feat/gitops-config-as-code Mode: Automated · Orchestrator (hybrid: backend built direct, Phase 3 via frontend implementer) · Incremental Started: 2026-06-21

Summary

A dockerfile or static workload can opt in to reading its deploy config from a .tinyforge.yml file in its own repo. Tinyforge fetches the file, shows it, computes drift vs the live config, and lets an admin sync (repo → live) with one explicit action. The repo becomes the source of truth for the declared fields; the UI locks those fields and renders a drift view.

v1 scope (deliberate)

• In: opt-in per workload (dockerfile/static only); .tinyforge.yml declares only source_config-resident fields (port, healthcheck, deploy_strategy, resources.{cpu_limit,memory_limit}, max_instances); manual explicit sync; declared-field drift view; GitOps-managed badge + read-only gate.
• Out (documented future seams): env/faces declaration (separate stores — needs typed multi-target apply); auto-apply-on-deploy (must be a Source-plugin concern, not a dispatch concern); multi-workload reconcile with create/delete (Framing B); image/compose sources (not git-backed / overlapping config surface).

.tinyforge.yml v1 schema

version: 1
deploy:
  port: 8080
  healthcheck: /healthz
  deploy_strategy: blue-green        # "" | recreate | blue-green (validated per source)
  resources: { cpu_limit: 0.5, memory_limit: 256 }
  max_instances: 1

No repo location, no tokens, no secrets — those stay in the encrypted DB.

Design constraints (from the adversarial review — non-negotiable)

• C1 Overlay is a typed ApplyPlan{SourceConfigPatch} routed to source_config only. env/faces are NOT in source_config (they live in workload_env / public_faces), so they are cut from v1; the typed plan reserves their slots for later.
• C2 No env in v1 → no secrets-in-repo hole.
• C3 No auto-apply-on-deploy in v1 (SHA is resolved inside src.Deploy; image has no repo). Future auto-apply lands as a Source-plugin concern.
• C4 Sync is explicit-action only, with a hard gate: parse → build overlay → omitted-field-preserving deep-merge onto a fresh copy of the live source_config → run Source.Validate on the merged result → persist in one transaction only if valid.
• C5 Drift is computed only over declared leaves, post-normalization (deploy_strategy:"" == "recreate"; YAML int vs JSON coercion). Omitted = unmanaged.
• Reuse staticsite.NewGitProvider (inherits SSRF defense); add a size-capped DownloadFile. Route all fetch errors through the existing sanitizeError(msg, token). Distinct no_file status. Sync audit is NOT deploy_history (rollback assumes deployable rows). Gate enable to dockerfile|static. Derive read-only fields from the declared overlay leaves (no provenance column). 4 additive gitops_* columns only.

Phases

#	Title	Subplan	Status
1	GitOps core (backend, no UI/mutation)	phase-1-core.md	✅ Done
2	Store + API (manual sync)	phase-2-api.md	✅ Done
3	Frontend experience (UI/UX showcase)	phase-3-frontend.md	✅ Done
4	Hardening + docs + final review	phase-4-hardening.md	✅ Done

Phase progress log

• Phase 1 — Done (2026-06-21). Migration (4 additive gitops_* columns) + Workload read path. New internal/gitops package: Spec/ParseSpec (KnownFields rejects unknown keys incl. env/faces attempts), source-aware ApplyPlan/BuildPlan (dockerfile: port/healthcheck/deploy_strategy; static: deploy_strategy only — resources/ max_instances dropped after confirming they aren't on dockerfile/static configs), MergeAndValidate (omitted-field-preserving + validate-then-commit), Drift (declared-only, normalized), Fetch (no_file/fetch_failed/invalid statuses, token-redacted). DownloadFile added to the GitProvider interface + 3 impls (64 KiB cap, ErrFileNotFound, SSRF-safe client reused, GitHub raw media type). Independent go-review: APPROVE, no CRITICAL/HIGH; M1 (GitLab doc comment) fixed; M2 (validate GitOpsPath at write) carried into Phase 2. 28/28 packages green.
• Phase 2 — Done (2026-06-21). Store setters SetWorkloadGitOps / RecordGitOpsSync (targeted column updates — disjoint from UpdateWorkload, so neither writer clobbers the other). API: GET /gitops (single rich payload: status + raw + live drift + meta — folded the separate /drift endpoint in to avoid a double fetch), PUT /gitops (admin, enable/disable + path, rejects non-eligible source + traversal/URL-injection paths), POST /gitops/sync (admin: fetch → MergeAndValidate → UpdateWorkload → RecordGitOpsSync → event-log audit). Sync recorded to event_log (not deploy_history — review S6). Tests: store round-trip + validGitOpsPath + planFields. Independent security review: clean, no CRITICAL/HIGH (token never leaks, SSRF locked by safe dialer, authZ correct, no field loss); LOW-1 (path query/fragment injection) hardened in validGitOpsPath. Full backend suite green.
• Phase 3 — Done (2026-06-21). Built by a frontend implementation agent. GitOpsPanel.svelte (self-fetching panel: status pill, purpose-built field-level drift view — repo→live per declared field on the forge/ember palette, .tinyforge.yml preview, enable ToggleSwitch, "Sync now" via ConfirmDialog, all five status states). api.ts fetchers + GitOpsStatus/GitOpsDriftEntry; gitops_* on the Workload TS type; GitOps-managed badge on the detail hero + apps list (payload already carries gitops_enabled); read-only edit-form banner (banner-only — hard-disabling inputs would need prop-threading through all 4 source forms; deferred). Backend managed_fields added to GET /gitops for the gate. i18n apps.detail.gitops.* en+ru (parity 1804/1804). Independent ts-review: one HIGH (isAdmin hardcoded true) + 2 MEDIUM — all fixed: real role wired via getCurrentUser() (panel default now false), stale-guard on the edit-open fetch, misleading eligible comment trimmed. check 0 errors · build · 26/26.
• Phase 4 — Done (2026-06-21). Concurrent-sync guard (review S5): a per-workload keyedMutex on Server; syncWorkloadGitOps locks by id and loads the row inside the lock, serializing the read→merge→write so two syncs can't race. Docs: docs/gitops.md (enable flow, v1 schema, drift/sync semantics, explicit "not in v1": env/faces, auto-apply, multi-workload, image/compose). Backend green. Final comprehensive review + merge gate next.

Amendment log

(plan changes require approval + an entry here)