Document base image policy and switch defaults to slim trixie

[fnando]

Closes #7.

What

• Document a written base-image policy and switch the defaults to rust:<v>-slim-trixie.
• Re-key builds.json so each entry carries a composite rust base key (<rust>[-slim]-<debian>, e.g. 1.94.0-slim-trixie). The same key flows verbatim into the published image tag: <cli>-rust<key>[-arch].
• Dockerfile FROM lines now reference the base image by digest only — FROM rust@${RUST_IMAGE_DIGEST} — never by tag. Variant + Debian codename surface in OCI labels via a RUST_BASE_SUFFIX build-arg.
• Thread the composite key through every consumer: tag-names.sh, build-image.sh, resolve-matrix.sh, smoke-test-image.sh, release-prepare.sh, release-body.sh, plus the matching workflow build-args, sbom/provenance filenames, and per-arch metadata.

Why

Issue #7 flagged that the Dockerfile hard-coded slim-bookworm without a written rule, and bookworm is now Debian oldstable. The policy section in RELEASE.md now spells out:

• Variant — use the slim upstream image. Non-slim SBOMs exceed the per-file size limit imposed by actions/attest, which fails the GitHub-native SBOM attestation step. The builder stage installs build-essential, ca-certificates, git, libssl-dev, and pkg-config explicitly because slim doesn't ship them.
• Debian codename — track the Debian release used by the latest Ubuntu LTS (currently 26.04 → Debian 13 / trixie), so users on the prevailing LTS aren't running on a Debian newer than what their host's upstream tracks.
• Tag — include variant + Debian in the image tag so future switches don't collide with the per-arch tag-immutability rule.

Notable details

• Image tag format becomes <cli>-rust<rust>-[slim-]<debian>[-arch], mirroring the upstream Rust image's own naming.
• The aliases job (:<cli>, :latest) is unchanged; it just resolves through the new composite default_rust value.
• The FROM rust@<digest> form means a RUST_VERSION or RUST_BASE_SUFFIX drift can no longer silently disagree with the bytes the digest pulls.
• build.yml gained a concurrency: block that cancels in-flight runs on PR pushes (main pushes still run to completion).
• smoke-test-image.sh now cross-checks org.opencontainers.image.base.digest against the digest pinned in builds.json for the rust base key, and org.opencontainers.image.revision against the declared stellar-cli ref — so a build that quietly used a different upstream base or commit would fail the smoke test.
• The image now carries only OCI standard labels (org.opencontainers.image.*); the previous org.stellar.* namespace was dropped because every value either duplicated an OCI label (stellar-cli-version ↔ image.version, stellar-cli-ref ↔ image.revision, rust-image-digest ↔ image.base.digest) or was derivable from other on-image data (rust-version and rust-base-suffix from image.base.name; build-arch from the manifest's platform.architecture).
• release-prepare.sh picks candidate rust base keys from Docker Hub's library/rust tag list, not rust-lang/rust's GitHub Releases. Rust toolchain releases ship to rust-lang/rust on GitHub the moment they're tagged, but the matching rust:<v>-<suffix> Docker image is built and published by the docker-rust team separately, often lagging by hours. Sourcing candidates from Docker Hub means the picker can only see versions whose image is actually pullable, so the workflow can never stage a release that names a key like 1.96.0-slim-trixie minutes before that tag exists on the registry. The local regex on the API response enforces the exact <x.y.z>-<suffix> shape, so an existing 1.96.0-trixie (different variant) or 1.96.0-slim-bookworm (different debian) won't get picked when the chosen suffix is slim-trixie.

End-to-end verification on a fork

Exercised the full pipeline against fnando/stellar-cli-docker with the new slim-trixie defaults and the Docker-Hub-driven picker:

1. release workflow run — picker resolved to 1.94.1-slim-trixie + 1.95.0-slim-trixie (not 1.96.0-slim-trixie, because rust:1.96.0-slim-trixie hasn't been published by the docker-rust team yet despite rust-lang/rust releasing 1.96.0 earlier the same day). Staged builds.json, opened the release PR.
2. Release PR #13 — reviewed and merged.
3. GitHub Release v26.1.0 — published; the publish workflow enriched the body with per-arch digests + copy-paste-runnable verify commands.
4. publish workflow run — all four per-arch builds (1.94.1 + 1.95.0 × amd64 + arm64) plus manifest, aliases, and release-body jobs all green. The SBOM attestation step fits the actions/attest size limit cleanly on slim.
5. Published images on Docker Hub at fnando/stellar-cli-experimental:
   • :26.1.0 (moving alias → 1.95.0-slim-trixie manifest list)
   • :26.1.0-rust1.94.1-slim-trixie, :26.1.0-rust1.95.0-slim-trixie (per-pair manifest lists)
   • Per-arch tags: :26.1.0-rust1.94.1-slim-trixie-amd64, …-arm64, :26.1.0-rust1.95.0-slim-trixie-amd64, …-arm64

Sample image labels

The labels on the freshly published 26.1.0-rust1.95.0-slim-trixie-arm64 image — 12 OCI standard labels, no custom namespace:

$ docker buildx imagetools inspect \
    docker.io/fnando/stellar-cli-experimental:26.1.0-rust1.95.0-slim-trixie-arm64@sha256:7ea3f587bf32de569d2bb98852e8dddf785628ece7979d49c96cb8514b8b77c0 \
    --format '{{ json .Image.Config.Labels }}' | jq .
{
  "org.opencontainers.image.base.digest": "sha256:e14e87345b4d5964ddcc3491d27ee046a0f23820f340c3c1e24da6880141f7c0",
  "org.opencontainers.image.base.name": "docker.io/library/rust:1.95.0-slim-trixie",
  "org.opencontainers.image.created": "2026-05-28T20:36:13Z",
  "org.opencontainers.image.description": "Stellar CLI image (SEP-58-compatible image for Stellar smart contracts).",
  "org.opencontainers.image.documentation": "https://github.com/fnando/stellar-cli-docker",
  "org.opencontainers.image.licenses": "Apache-2.0",
  "org.opencontainers.image.revision": "1228cff8022b804659750b94b315932b0e0f3f6a",
  "org.opencontainers.image.source": "https://github.com/fnando/stellar-cli-docker",
  "org.opencontainers.image.title": "stellar-cli",
  "org.opencontainers.image.url": "https://github.com/fnando/stellar-cli-docker",
  "org.opencontainers.image.vendor": "Stellar Development Foundation",
  "org.opencontainers.image.version": "26.1.0"
}

image.base.name carries the human-readable rust:1.95.0-slim-trixie (variant + Debian + version); image.base.digest is the multi-arch index digest pinned in builds.json; image.revision is the upstream stellar-cli commit SHA. Everything else needed for verification is in the manifest itself.

Local test plan

• ./scripts/validate-json.sh, ./scripts/validate-shell.sh, shellcheck scripts/*.sh scripts/lib/*.sh — all clean.
• ./scripts/build-image.sh --stellar-cli-version 26.0.0 --rust-version 1.94.0-slim-trixie builds successfully.
• ./scripts/smoke-test-image.sh --image stellar-cli:26.0.0-rust1.94.0-slim-trixie --stellar-cli-version 26.0.0 --rust-version 1.94.0-slim-trixie — passes all four OCI label assertions, including the image.base.digest cross-check against builds.json and the image.revision cross-check against the declared stellar-cli ref.
• Inspected the upstream digests: all pinned digests resolve to application/vnd.oci.image.index.v1+json multi-arch indexes.

[Copilot]

Pull request overview

This PR formalizes how Rust base images are selected/pinned and updates the repo to use composite Rust base keys (variant + Debian codename), switching the default pairing to *-slim-trixie and ensuring Docker builds reference Rust base images by digest.

Changes:

• Re-keys builds.json to use composite Rust base keys (e.g. 1.95.0-slim-trixie) and threads the new key through scripts and workflows.
• Updates the Dockerfile to FROM rust@<digest> (digest-only), surfacing human-readable base info via OCI labels.
• Enhances validation/smoke-test behavior and refresh/release tooling to work with the new key scheme and digest pinning.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
scripts/tag-names.sh	Builds canonical tags using the composite Rust base key.
scripts/smoke-test-image.sh	Validates OCI labels and cross-checks base digest + cli revision.
scripts/resolve-matrix.sh	Emits workflow matrix rows including parsed version/suffix from composite key.
scripts/repro-test.sh	Updates examples to reflect new tag format.
scripts/release-prepare.sh	Picks default Rust base keys from Docker Hub tag listings and threads suffix.
scripts/release-body.sh	Groups/sorts release metadata by composite key and bare Rust version.
scripts/refresh-rust-digests.sh	Refreshes pinned digests by inspecting rust:<key> upstream tags.
scripts/newest-pair.sh	Reports newest (cli, rust base key) pairing.
scripts/lib/common.sh	Adds key parsing helpers and updates digest/pair resolution for composite keys.
scripts/build-image.sh	Builds local images using composite keys and passes suffix/version build args.
RELEASE.md	Documents base image policy and updates release process examples for new tags/keys.
README.md	Updates user-facing docs and examples to the new tag/key scheme.
Dockerfile	Switches to digest-only FROM rust@... and standardizes on OCI labels.
builds.schema.json	Renames/validates Rust version fields to composite rust base keys.
builds.json	Migrates stored rust digests and cli pairings to composite keys; updates defaults.
.github/workflows/release.yml	Updates release workflow messaging to “rust base” terminology.
.github/workflows/publish.yml	Threads composite key/suffix through tagging, build args, artifacts, and metadata.
.github/workflows/build.yml	Adds concurrency cancellation for PRs and updates smoke build tag derivation.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.