Common-Case Freight + Rendered Branches

[snickell]

Common-Case Freight + Rendered Branches

Short name: Common-case render

Catchy description: Stop manufacturing a fake build-lock commit. Let Kargo assemble the real monorepo commit and the real image into one Freight, then render stage branches from sparse checkouts of the huge repo.

Detailed Technical Description of Plan

This plan is the “use the real artifacts, not a synthetic release record” option. Kargo watches the actual app image in GHCR and the real code-dot-org Git history, then creates one Freight item only when those two match on the same git-<full-commit-sha> identity. That means the release coordinate is not a warehouse file in k8s-gitops; it is the pairing of the published image and the source commit that produced it. The Warehouse logic is therefore the heart of the plan: if the image tag and Git commit do not line up exactly, there is no promotion candidate.

On the GH action side, Helm CI only builds and publishes the immutable git-<full-commit-sha> image tag, and it writes no package artifact and no Git Freight record.

Promotion then uses that single Freight item to render deploy output into long-lived stage branches in k8s-gitops. The critical implementation detail is that render-time input comes from a sparse checkout of code-dot-org at the promoted commit, not from the moving staging branch tip. Kargo clones k8s-gitops once for env policy and metadata, clones code-dot-org once for the source package, renders the stage-specific output, and commits that rendered output to stage/<deployment>. The review stage is not a special case in architecture, only in Git behavior: production output gets rendered to a generated branch and opened as a PR against stage/production so humans review the actual manifests before production sync.

This plan differs from the thin-lock and snapshot families in where trust lives. The thin-lock family trusts a tiny build-lock file, and the snapshot family trusts a frozen copy of the package. Common-Case trusts the live source commit plus the live image tag, so the tricky part is making promotion deterministic without snapshotting anything into Freight. The hard implementation points are the exact git-<full-commit-sha> pairing rule, the sparse checkout at the promoted source commit, and the Helm render inputs assembled from k8s-gitops envType values plus the shared deployment metadata.

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

common-case-rendered-branches

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