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 Helm chart files; 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 Helm must have a predictable internal layout that
downstream steps can trust.

For Helm, the capsule is mostly a frozen chart plus values. That means the
capsule 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. For this handoff, the full capsule form is the
required implementation target. Treat the package-pair text below as future-only
context, not as a co-equal first-pass option.

• It is: Helm plan
• It uses: hybrid pattern

oci-release-capsule

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