Sambee 0.9

Promote Docker Candidate

This is step 2 of the Docker release flow.

Use this Release: Publish Docker Image workflow to move Docker channel pointers to an already signed, immutable build.

How To Trigger the Workflow

Use this order:

  1. Identify the approved canonical build tag, build-vX.Y.Z.
  2. Create the public Git tag vX.Y.Z on that same commit.
  3. Add sambee-release.json to the draft public release with schema_version, version, build_tag, source_sha, and component_scope.
  4. Set component_scope to docker or both, then publish the GitHub Release.

For example, if the approved commit is 89378a28b18ba6532571e62734a6a9aefac6c99a and VERSION is 0.7.0:

git tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m "Sambee 0.7.0"
git push origin v0.7.0

In the GitHub web UI, create a release from the existing tag. Avoid the branch selection.

Validation

Before promotion, the workflow checks all of the following:

  1. The release tag is exactly v$(cat VERSION) and is not a prerelease.
  2. The corresponding build-v<version> Git and GHCR markers identify the same source and image.
  3. sambee-release.json authorizes Docker or both components and matches the version, build tag, and source SHA.
  4. The candidate image labels match the expected revision, checked-in product version, and source repository.
  5. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived .meta tag and matches the candidate digest.

If any of those checks fail, promotion stops.

Published Tags

Docker promotion moves only mutable pointers:

  • The moving minor-series tag, such as 0.7.
  • The moving channel tag stable.

The exact X.Y.Z, source-SHA, and build-vX.Y.Z tags were created by the build workflow and are immutable.

After the tag-promotion steps finish, the workflow uploads metadata.json, provenance/intoto.jsonl, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived .meta artifact in ghcr.io/<owner>/sambee-signatures remains the canonical metadata bundle.

The build workflow signs the digest with Cosign before it assigns immutable registry markers. Promotion only moves pointers after verifying that published artifact.

Why No Rebuild

This model avoids rebuilding at release time.

The image tested as a preview candidate is therefore the exact same image that later becomes stable or beta. The preview-generated SBOM and provenance bundle is also verified against that same digest during promotion.

Tag Contract

Docker image promotion expects a plain release tag matching the checked-in version from VERSION.

Examples:

  • VERSION contains 0.7.0.
  • A stable Git tag and GitHub Release must be v0.7.0. If those values drift apart, promotion fails.