Chapter 36Lesson 03~185 minutes

Docker in CI/CD: Reproducible Builds, Buildx, Registry Caching, Ephemeral Runners, and Release Promotion: Configuration, Design Choices, and Tradeoffs

Choose builder lifecycle, cache trust scope, release triggers, multi-platform strategy, registry retention, and attestation gates by observable state and rollback requirements.

Cache trustMulti-platformRelease policyAttestationsTradeoffs

Learning objectives

Choose shared or ephemeral builders based on trust, persistence, cost, and evidence needs.
Define cache read/write scopes that accelerate trusted builds without letting untrusted jobs poison release state.
Choose branch, pull-request, release and promotion triggers without rebuilding the release artifact.
Design multi-platform build and promotion around an index digest and platform-specific verification.
Define registry retention and signing/attestation gates as policy over immutable subjects.

1. Builder lifecycle: shared performance versus ephemeral cleanliness

Choice	Benefits	Costs/risks	Good fit
Shared persistent builder	warm cache; low startup latency	cross-job state; harder provenance; cleanup/credential discipline	trusted dedicated team/build host
Ephemeral builder per job	clean state; easier ownership; deterministic teardown	cold-start and cache-import overhead	untrusted/isolated CI and high-assurance releases
Remote managed builder	centralized performance and multi-platform capacity	service trust, tenancy and credential boundary	teams needing scalable isolated build workers

2. Cache trust scope is more important than cache hit rate

Separate cache namespaces by image and trust domain. A release branch may import a broadly readable cache while writing only to a protected cache reference. A fork should not receive credentials that let it overwrite the protected cache. Cache entries accelerate a build; they do not prove the release artifact is trusted.

3. Registry cache versus inline cache

Backend	Use when	Tradeoff
inline	simple single-image workflows	cache metadata travels with image; limited separation/control
registry	ephemeral runners and larger reusable caches	separate cache object/reference; needs registry auth and retention policy
local	developer/lab or persistent workspace	not naturally portable across ephemeral runners
gha	GitHub-hosted workflow convenience	provider-specific scope/quota/API behavior

4. Branch builds and release builds should have different authority

Branch and pull-request builds usually need build/test authority only. Release jobs need registry write, optional signing/attestation identity, and promotion rights. Split these credentials and triggers. A protected release event should consume the digest from the tested build rather than re-running the Dockerfile.

5. Digest promotion versus rebuild

Pattern	Artifact identity	Recommendation
rebuild per environment	new digest at each stage	avoid when goal is promotion; evidence fragments across builds
copy/retag same digest	one digest across environments	preferred for release promotion
mutable tag only	ambiguous over time	use as convenience pointer, never sole release evidence

6. Multi-platform strategy

Buildx can produce a multi-platform index. Record the index digest plus its platform manifest digests. Test each platform where behavior differs. Promotion should normally move the tested index as one unit. If native builders are split across nodes, keep builder-node identity and per-platform logs in the evidence packet.

7. Provenance and SBOM gates

Minimal provenance is a useful baseline because it records source/build facts without the richer build-argument exposure of max mode. Use max provenance when your policy needs it and your build parameters are safe to disclose. SBOM is opt-in and should be validated against the digest. A gate should verify presence/content/identity before promotion; merely generating an attestation is not equivalent to trusting it.

8. Registry namespace and retention

Object	Retention idea	Reason
release digests	long-lived/immutable retention	rollback and audit
branch tags	shorter retention	high churn; convenience only
registry cache	budget/TTL by image + trust domain	performance state, not release record
attestations/signatures	retain with subject digest	supply-chain evidence must remain resolvable

9. Docker-maintained GitHub Actions are optional, not the conceptual model

At this baseline docker/setup-buildx-action@v4 and docker/build-push-action@v7 are current major lines; the latest releases are v4.3.0 and v7.4.0. Pin reviewed action revisions according to your organization’s policy rather than assuming a floating major is sufficient. The portable concepts remain source SHA, builder identity, cache scope, digest, attestations and promotion.

10. Worked decision scenario

Requirement	Decision	Evidence
Public fork PRs	ephemeral hosted runner; no registry write; isolated cache write scope	runner instance, source SHA, builder, test output
Protected main	ephemeral builder; protected registry-cache write	cache ref/scope, image digest, provenance
Signed release tag	promote tested digest; no rebuild	subject digest, signature/attestation, alias before/after
Production rollout	deploy digest or alias pinned by recorded digest	runtime pull/deployment digest

11. Rollback

Rollback should select a previously verified digest, not rebuild an old Git tag against today’s base image ecosystem. Keep the old digest, its attestations, test evidence and deployment compatibility record long enough to support the rollback window.

12. Version/platform prerequisites

Record actual Buildx/BuildKit versions and driver capabilities. The default docker driver’s external-cache and attestation behavior depends on the Docker image store; docker-container, remote and other external BuildKit drivers have different persistence/output behavior. Hosted providers add their own token, cache, runner and artifact semantics.

Knowledge check

Why should an untrusted fork not write the protected main cache?

What is the cleanest rollback artifact?

When is max provenance inappropriate?

Why retain attestations as long as the release digest?

What should multi-platform promotion usually move?

Next lesson

Next: Docker in CI/CD: Reproducible Builds, Buildx, Registry Caching, Ephemeral Runners, and Release Promotion: Diagnostics, Failure Modes, Security, and Performance

Continue with the next lesson in the course sequence and carry forward the evidence-first Docker operating model.

Official references and version notes

Design baseline: 2026-09-22. External cache, attestation and provider-action behavior remains version/driver/provider sensitive; lessons therefore require recording actual versions and trust scopes rather than assuming one hosted CI implementation.

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.

Keep the academy open

Support free, practical DevOps education.

Every lesson is designed to remain readable in a browser, downloadable from GitHub, and usable without a paid learning platform. Contributions help expand and maintain the curriculum.

Ethereum / ERC-20

0x716c4Ab160C4B66F31a28AE2448BfF68fc3a2ef0Send only Ethereum/ERC-20 compatible assets to this address.