OCI Release Capsule

[snickell]

OCI Release Capsule

• Short name: OCI Capsule
• Catchy description: Make one immutable registry object the center of release
  truth, then render from that object instead of chasing source at promotion
  time.

Detailed Technical Description of Plan

This plan makes the release object itself an OCI artifact, not a Git commit or a
rendered branch. The app image and the capsule share the same
git-<full-commit-sha> identity, and the capsule carries the exact deploy
package plus release metadata. Promotion is therefore a two-step trust chain:
first verify that the promoted image and capsule belong to the same release
identity, then unpack the capsule and render from the package stored inside it.
That is what makes this plan different from the rendered-branch plans: the
output is still reviewable, but the thing Kargo promotes is an immutable
registry object instead of a live source checkout or a synthetic Git release
record.

The capsule should be thought of as a frozen release bundle with a small,
explicit schema. release.yaml names the image ref, digest, package kind, and
package path; the package/ tree contains the shared Kustomize package; and
metadata/ carries provenance and SBOM data. Promotion must download the
capsule, confirm the tag/digest/package metadata match the Freight identity,
and then render from the exact path recorded in the capsule. The important
tricky part is that the capsule is not a generic blob archive: the package path
inside the artifact is part of the contract, so Kustomize packaging and the
downstream render step must have a predictable internal layout that Kargo can
trust.

For this plan, the capsule is the required implementation target. The Kustomize
form still depends on k8s-gitops for environment shaping, but it does not
depend on live code-dot-org source at promotion time. The alternate package
pair form in this doc is intentionally weaker and more incremental: it keeps the
same image+package pairing but splits the release witness into Git plus OCI
artifacts. The full capsule is the stronger, more opinionated version when the
team wants one registry-native release object to own both the deploy payload and
its provenance.

• It is: packaging-agnostic plan
• It uses: hybrid pattern

oci-release-capsule

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