# 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

```yaml
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](phase-1-core.md) | ✅ Done |
| 2 | Store + API (manual sync) | [phase-2-api.md](phase-2-api.md) | ✅ Done |
| 3 | Frontend experience (UI/UX showcase) | [phase-3-frontend.md](phase-3-frontend.md) | ✅ Done |
| 4 | Hardening + docs + final review | [phase-4-hardening.md](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)_