P2 (ADR-067): Promotion — promote-by-digest, auto ≤ staging, gated prod

[gangster]

ADR-067 Phase 2 / §8. The same signed artifact (by digest) moves up the Stage ladder: auto-promote up to staging, gated review for prod (separation of duties). To be decomposed into sub-issues when designed (the way P4 was).

Part of #369.

Scope sketch

• Promotion = a digest-bump to the next stage's overlay (GitOps), not a rebuild — the same image promotes.
• Auto ≤ staging; prod is gated (author ≠ approver). This is the demand side of the release-approver role designed in ADR-068 P4.5 (P4.5 (ADR-068): release-approver + gated prod promotion #366) — coordinate so the gate + CODEOWNERS projection are shared, not duplicated.
• Prod standing posture = view; prod mutates only via the gated promotion PR + break-glass (ADR-040).
• Consider Argo Rollouts / progressive delivery (ADR-056) as the rollout mechanism.

Cross-links: ADR-068 #366 (release-approver), ADR-056 (progressive delivery).

[gangster]

Partial resolution — ADR-071 delivered the promote-by-digest mechanism (single-stage proven live)

The ADR-071 control-plane digest promotion epic (now Accepted) builds the core machinery this issue's scope sketch calls for. Status against the sketch:

Done / proven live (dev stage):

• ✅ Promotion = a digest-bump in GitOps, not a rebuild. The deployed digest is now Environment state — a Release record at gitops/releases/<team>/<product>/<stage>.yaml (CRD releases.platform.refplat.org, PR feat(crossplane): ADR-071 PR1 — Release CRD (control-plane deployed-digest record) #445), separate from the human-owned XEnvironment claim. App main is never CI-written.
• ✅ Promotion happens via a gated PR. App build-sign → promote.yml (running as the asanexample-promote GitHub App) opens a Release PR → the existing gitops Gate validates/classifies releases (PR feat(gitops-gate): ADR-071 PR2 — Release digest gate (validate + classify) #446) and auto-merges → the per-Product ApplicationSet injects the new digest via a merge generator (PR feat(argocd-apps): ADR-071 PR4 — ApplicationSet injects the Release digest (B-via-Helm) #451, B-via-Helm). Proven end-to-end on app-alpha-shop: build → Release PR → auto-merge → pod rolled, with zero CI commits to the app repo (re-protected main).
• ✅ The Terragrunt-derived per-Product plumbing reconciles on a new Product (registry-reconcile, PR feat(ci): ADR-071 PR7a — registry-reconcile (close the per-Product apply seam, Gap #2) #448 + the cron trigger feat(ci): reliable registry-reconcile trigger + starter promote pin (hands-off New Product) #459).

Still open — the multi-stage ladder + prod gating (the heart of this issue):

• ⬜ The Stage ladder itself. Only single-stage (dev) is proven. Need the same digest to promote dev → staging → prod (per-stage Release records + the promotion trigger between stages).
• ⬜ Auto ≤ staging, gated prod (author ≠ approver). This is the demand side of the release-approver role from ADR-068 P4.5 (P4.5 (ADR-068): release-approver + gated prod promotion #366) — coordinate so the gate + CODEOWNERS projection are shared, not duplicated. The ADR-071 Gate currently auto-merges all Release PRs; prod needs the admin-review path.
• ⬜ Prod standing posture = view; prod mutates only via the gated promotion PR + break-glass (ADR-040).
• ⬜ Consider Argo Rollouts / progressive delivery (ADR-056) as the rollout mechanism.

Net: the transport (signed digest → control-plane Release → gated PR → ApplicationSet inject) is built and live; what remains is the stage-to-stage promotion flow and the prod approval gate. Keeping this open to track that — decompose into sub-issues when the ladder + release-approver (#366) are designed together.

Refs: ADR-071 (Accepted, #444); PRs #445/#446/#447/#448/#451/#453/#454; trusted-ci #12/#13/#14. See docs/architecture/cosign-image-signing.md and the ADR-071 plan.