# ADR-0004 — GitOps engine: Flux CD
- Status: Accepted
- Date: 2026-08-15
- Serves: R-GITOPS-01, R-GITOPS-02, R-GITOPS-03, R-UPD-02, R-SEC-01, R-ENV-02
- Supersedes: —

## Context
All desired state must be reconciled from git (pull-based), with drift correction, environment
overlays (dev↔prod), encrypted secrets, and — critically — **hands-off image updates** driven by
declared policy (R-UPD-02). The GitOps engine choice is tightly coupled to the update mechanism and
the secrets model.

## Decision
Use **Flux CD** for reconciliation, chosen decisively because it *natively* provides the two
capabilities that matter most for this platform's hard requirements:
- **image-update-automation** (image-reflector + image-automation controllers) for policy-driven,
  no-human image updates (R-UPD-02, ADR-0009).
- **native SOPS decryption** for encrypted-in-git secrets (R-SEC-01, ADR-0007).
Flux Kustomize/Helm controllers handle overlays (dev↔prod, R-ENV-02) and chart-based platform
components.

## Alternatives considered
- **Argo CD** — excellent UI and ApplicationSets; but image auto-update (Argo Image Updater) and
  secret decryption are add-ons rather than first-class, and the platform gets its UI from the C2
  composition ([12](../docs/12-command-center-ui.md)) rather than from the GitOps tool. Reasonable
  alternative; Flux wins on native image-automation + SOPS fit.
- **Rancher Fleet / Kustomize-only + CI push** — weaker fit for the automated-update and drift
  requirements.

## Consequences
- Native, first-class path to R-UPD-02 (no bolt-on for automated updates) and R-SEC-01 (SOPS).
- GitOps status/health is surfaced in the C2 UI via Headlamp/Flux views ([12](../docs/12-command-center-ui.md)),
  not via a bundled GitOps GUI.
- Reconciliation failures/drift are alerting conditions (R-OBS-04).
- If a rich built-in GitOps GUI later becomes a priority, revisit via superseding ADR (Argo).