Rendered Branches from a Thin Lock

[snickell]

Rendered Branches from a Thin Lock

Short name: Rendered branches

Catchy description: Keep the warehouse artifact tiny, but make every promotion render full stage-specific manifests into stage branches so humans review the real output, not just a ref change.

Detailed Technical Description of Plan

This plan keeps the release signal intentionally small: a single Git build-lock record in k8s-gitops identifies the exact code-dot-org commit and image tag to promote, but it does not store rendered manifests as Freight. Kargo uses that lock only as the release coordinate. The real work happens during promotion, where Kargo checks out the exact source commit, combines it with the latest GitOps environment policy, and writes stage-specific rendered output into k8s-gitops stage branches. Argo CD then deploys from those rendered branches, so the thing humans review is the actual manifest output that will hit the cluster.

The technical trick is that the plan is Kustomize-only without changing the release model. Promotion starts from the checked-in code-dot-org/k8s/kustomize/ tree plus the GitOps envType components and a reusable deploy-wrapper template in k8s-gitops; the wrapper is copied into a temp work dir, rewritten for the target deployment, and then built into the rendered branch. The important distinction is that the package is materialized at promotion time, not in Freight, and the stage branches are consumed the same way.

The tricky parts are the ones that make the reviewable-output model honest. Promotion has to render from the exact promoted commit, not from the moving branch tip, and it has to write into a stage-specific branch/path that Argo can watch directly. review-infra-changes is the key control point: production output is rendered to a PR branch, reviewed as generated manifests, and only then merged into stage/production. That makes this plan fundamentally different from the thin-lock or source-snapshot families: the lock is tiny, but the review surface is the full rendered manifest tree, so the implementation must preserve a clean split between source checkout, GitOps policy, and generated output.

• Type: Kustomize
• Pattern: Hybrid
• Rendered manifests pattern: Yes

rendered-branches

Sibling PR: code-dot-org/code-dot-org#71568