Source Snapshot (Kustomize) + Rendered Branches

[snickell]

Source Snapshot (Kustomize) + Rendered Branches

Short name: Source snapshot + render

Catchy description: Freeze the deploy source package once per release, keep environment policy in GitOps, and let Kargo render stage-specific outputs from that frozen snapshot into reviewable rendered branches.

Detailed Technical Description of Plan

This plan is the middle ground between live-source rendering and a richer OCI release artifact: CI freezes the deploy package once, writes that snapshot into warehouses/codeai/freight/git-<full-commit-sha>/, mirrors the exact same contents to current/, and then Kargo renders every downstream stage from that frozen release record. Promotion does not chase the moving code-dot-org branch tip. It reads warehouses/codeai/freight/current/freight.yaml, resolves the release identity and package type from there, and uses GitOps-side env policy to materialize the stage-specific output into a rendered branch. That gives you a release object that is still plain Git, still reviewable, and still easy to audit by path, but without the ambiguity of reconstructing release truth from live source during promotion.

The snapshot is the durable k8s/kustomize/ tree, but promotion still does not render from that tree directly. Instead, Kargo assembles a temporary deploy wrapper from k8s-gitops/apps/codeai/kargo/templates/deploy/, layers in the envType Component files from apps/codeai/envTypes/<envType>/, and points that wrapper at the frozen base/ and components/ payload in the snapshot before running kustomize-build. The important implementation detail is that the snapshot stays literal while the stage branch becomes the only mutable review surface.

The tricky part is not the rendering step itself; it is keeping the snapshot contract disciplined. current/ must remain an exact mirror of the historical git-<full-commit-sha>/ directory in the same commit, because promotion reads only current/ while humans and audit tooling may inspect the historical release directory. That makes this plan easier to reason about than the live-source plans, which must sparse-checkout the huge monorepo at the promoted commit, but less compact than the thin-lock family because it duplicates the deploy package into GitOps-adjacent Freight. In practice, this is the plan to choose when you want frozen release inputs and rendered-branch reviewability without introducing a second artifact system.

• Type: Packaging-agnostic
• Pattern: Hybrid
• Rendered manifests pattern: Yes

source-snapshot-rendered-branches

Sibling PR: code-dot-org PR #71570