ADR-0034 — Environment & promotion model (promote by digest via PR)
- Status: Deferred
- Date: 2026-06-11
- Related: platform/03 environments, platform/08 releases, ADR-0028
V1 Freeze (2026-06-12): Deferred. V1 is single-environment. Promote-by-digest across dev/staging/prod re-opens at P4 (multi-env).
Context
A change must climb from dev to production with increasing confidence, and “it worked in staging” must mean the exact bytes that will run in prod worked. Two common anti-patterns threaten this: rebuilding per environment (different bytes per stage) and branch-per-environment (drift, cherry-pick hell).
Decision
- Build once; promote the immutable image digest dev → staging → prod. No rebuild per environment (platform/01).
- Promotion = a PR in the GitOps repo moving the pinned digest from one environment’s values to the next (ADR-0028) — reviewable, auditable, revertable.
- Environments are directories (one branch), not env branches; differences are Helm values overlays only (scale, tier, endpoints, flags), never code or image.
- Gates: auto dev → staging on green CI; manual approval + green staging soak/load + open sync window for staging → prod; prod via canary (ADR-0029).
- Ephemeral preview envs per PR via ApplicationSet PR generator, reaped on close.
Consequences
Positive
- “Tested in staging” = those exact bytes → high-fidelity confidence.
- Promotion + rollback are Git operations (revert a PR) → auditable, fast.
- Strong environment parity (only values differ) reduces “works in staging, breaks in prod” surprises.
Negative / costs
- Requires discipline: no env-specific image builds, no config drift beyond values.
- Per-PR previews cost compute (bounded by TTL + quotas, platform/02).
Alternatives considered
- Rebuild per environment: different bytes per stage → “works here, not there”. Rejected.
- Branch-per-environment: drift + cherry-pick hell. Rejected for directories + PR promotion.
- Auto-promote to prod (no gate): viable once canary analysis is fully trusted; we start gated and relax per-service as confidence grows.
Scaling
ApplicationSet generators render the (service × env) matrix from few manifests (ADR-0028); independent per-service digests + PRs allow independent cadences; the platform version is a manifest of component digests.