Docker in CI/CD: Reproducible Builds, Buildx, Registry Caching, Ephemeral Runners, and Release Promotion: Concepts, Architecture, and Mental Model

1. The practical problem: “the pipeline passed” is not an image identity

A CI system can report success while still leaving an ambiguous release. A mutable tag may move after testing. A deployment job may rebuild from the same branch but obtain a newer base image. A shared cache may inject unreviewed state. A release alias may be updated before the registry has the intended index. The cure is to make the immutable digest—not the job name or tag—the release subject.

The operating rule for this chapter is build once, verify that digest, then promote the same digest. If a later stage rebuilds, it has created a new artifact and must repeat the verification chain.

2. Causal model: source revision to runtime identity

flowchart TD
  A[Exact source SHA] --> B[Ephemeral trusted builder]
  B --> C[BuildKit graph + scoped cache]
  C --> D[Image/index digest]
  D --> E[Tests + SBOM + provenance]
  E --> F[Registry subject digest]
  F --> G[Promotion alias / environment]
  G --> H[Runtime pull + digest verification]
  D --> I[Evidence packet]
  E --> I
  F --> I
  H --> I
            

The source SHA fixes the repository state. The builder identity and versions describe who/what executed the build. The cache can accelerate execution but must not replace source or base-image identity. The image/index digest names the resulting bytes. Tests and attestations describe properties of that digest. Promotion changes a human-facing alias or environment pointer, not the digest. Runtime verification closes the loop by proving what was actually pulled or started.

3. Separate state domains before automation

4. Tags are routing labels; digests are artifact identity

A branch tag such as main or a release tag such as v2.4.0 is useful for humans and automation, but it is mutable registry metadata. The registry digest is content-addressed. Your promotion record should therefore say “alias X now resolves to digest Y,” not merely “we pushed X.”

5. Buildx and BuildKit in ephemeral CI

Ephemeral runners intentionally discard local daemon and filesystem state after a job. BuildKit solves the performance cost by exporting cache to an explicit backend and importing it on the next run. Current Buildx supports local, inline, registry and GitHub Actions cache backends in common configurations. The cache key/scope is part of the security design: caches shared across forks or unrelated trust domains can become a supply-chain input.

6. Read-only preflight first

set -eu
printf 'context=%s
' "$(docker context show)"
docker version
docker buildx version
docker buildx ls
docker buildx inspect --bootstrap

Record the actual installed versions instead of assuming the course baseline. In 2026-09-22 upstream Buildx 0.37.1 and BuildKit 0.33.0 are current, but Docker Desktop, distro packages, CI images, and managed builders may package different versions.

7. Cache is an optimization input, not release identity

8. Build, test, publish and promote are different verbs

• Build: produce an image/index from declared inputs.
• Test: execute checks against that exact result or a digest-equivalent pull.
• Publish: store the result under a registry repository and capture its digest.
• Attest: attach provenance/SBOM claims to the digest.
• Promote: move a release/environment alias to the already-tested digest.
• Deploy: pull/run and verify the digest in the target environment.

9. Current attestation behavior matters

BuildKit creates minimal provenance by default for supported registry outputs. SBOM is opt-in. Attestations are attached to an image index and survive when pushed to a registry; loading into a classic local image store can lose or reject them. Docker-maintained GitHub Actions additionally have provider-specific provenance defaults. Never pass secrets through build arguments: provenance may intentionally record build parameters.

10. Multi-platform releases have two digest levels

A multi-platform tag resolves to an image index digest, which in turn references per-platform manifest digests. Promotion normally targets the index digest so all tested platforms move together. If only one platform is promoted, record that narrower subject explicitly.

11. Evidence ledger

12. Safe baseline for this chapter

• Never publish only latest as release evidence.
• Never rebuild in a deployment stage and call it promotion.
• Never share write-capable caches across untrusted forks by default.
• Never use build arguments for secrets; use BuildKit secret/SSH mounts.
• Keep runner/builder credentials short-lived and scoped.
• Delete only exact disposable builders, registry containers and lab directories.

Knowledge check

Official references and version notes

• Docker Docs — Build with CI — CI patterns around Buildx/BuildKit and provider integrations.
• Docker Docs — Cache storage backends — inline, local, registry, and GitHub Actions cache backends and scope considerations.
• Docker Docs — Registry cache — external registry cache configuration and separation from the release image.
• Docker Docs — docker buildx build — metadata files, cache import/export, push, SBOM and provenance controls.
• Docker Docs — Build attestations — default provenance and SBOM/provenance persistence rules.
• Docker Docs — GitHub Actions attestations — current Docker-maintained action behavior and provenance/SBOM inputs.
• Docker Docs — GitHub Actions cache management — provider cache integration and limits.
• Docker Docs — docker buildx imagetools create — create/retag registry manifests without rebuilding.
• Docker Docs — Builders — builder instances, drivers, workers, and lifecycle.
• Docker Buildx releases — version source; v0.37.1 is current at this chapter baseline.
• Moby BuildKit releases — version source; v0.33.0 is current at this chapter baseline.
• docker/build-push-action releases — v7.4.0 current at this baseline.
• docker/setup-buildx-action releases — v4.3.0 current at this baseline.
• Docker Engine 29 release notes — Engine 29.8.1 baseline and bundled/runtime changes.