For a fleet of services built in CI, when is a single multi-stage Dockerfile per service the right structure, versus a shared prebuilt builder image, versus having an external build system hand the Dockerfile a finished artifact? What tradeoffs drive that call?

## The question behind the question Every container build has to answer: *where does the toolchain come from, and who guarantees the artifact matches the source?* Multi-stage builds let you put the toolchain inside the Dockerfile, but that is a choice, not a law. At fleet scale the choice has cost, ownership and audit consequences. ## Option A — self-contained multi-stage Dockerfile ``` FROM eclipse-temurin:21-jdk AS build ... resolve deps, compile, test ... FROM eclipse-temurin:21-jre COPY --from=build /src/build/libs/app.jar /app/app.jar ``` **Strengths.** One artifact of truth: the repo. A new engineer, an auditor or a security responder can `docker build .` on any machine and obtain the image; there is no "you had to have Node 22 and protoc installed" folklore. CI runners stay dumb and interchangeable. Supply chain is legible because everything the build touched is named in the file. **Costs.** Cold builds pay for the full toolchain pull and dependency resolution every time cache is absent — which on ephemeral runners is every time, unless you invest in remote cache. The toolchain definition is duplicated across every service, so bumping a JDK or a linter across 40 repos is 40 pull requests and a long tail of stragglers. **Fits.** Small-to-medium fleets, polyglot estates where no toolchain is shared widely, open-source repos, anything with a strong reproducibility or attestation requirement. ## Option B — shared prebuilt builder image A platform team publishes `org/builder-jvm:2026.08` containing the JDK, the build tool, linters, scanners and CA configuration. Service Dockerfiles start `FROM org/builder-jvm@sha256:… AS build` and contain only the service-specific steps. **Strengths.** The expensive, rarely-changing part is built once and shared, so cold builds shrink dramatically. Toolchain upgrades become one image release plus a bump (automatable with a dependency bot). The builder image is scanned and attested centrally, so security review has one target instead of forty. Standardisation makes per-service Dockerfiles short enough that people actually read them in review. **Costs.** You now own an internal image with a lifecycle: versioning, deprecation, breakage when it changes under a service. Pin by **digest**, not a floating tag, or you have reintroduced non-reproducibility with extra steps. There is real drift risk between the builder image and what developers have on their laptops. And a compromised builder image compromises every service — it is a high-value supply-chain target that deserves provenance and restricted publish rights. **Fits.** Fleets with a dominant language or two, a platform team that exists, and CI cost that is actually measured. ## Option C — external build, thin Dockerfile CI runs the build system natively, then the Dockerfile is a handful of lines that copy the resulting artifact into a runtime base. **Strengths.** The fastest option in practice, because the build system's incremental cache — often far smarter than layer caching, with per-module granularity and remote caching — is reused directly. It fits monorepos where one command builds many services, and it avoids sending a huge context into a builder. **Costs.** Hermeticity is gone: the artifact reflects whatever the runner had installed. `docker build .` no longer reproduces anything; "how was this image made" is answered by CI configuration rather than by a file in the repo. Local parity suffers most for exactly the people who need it — someone debugging a production-only failure. Mitigate with pinned toolchain versions in the repo, a lockfile, and provenance attestation recorded at build time. **Fits.** Large monorepos with a mature build system and remote cache, where build minutes dominate and the platform team can supply the missing reproducibility guarantees another way. Note that build-tool-native image builders live in this space too; they are their own topic and the point here is only that choosing them means choosing option C's tradeoffs. ## Cross-cutting factors - **Cold vs warm economics.** If runners are ephemeral, cold-build cost is your *typical* cost, not the worst case. Measure it before optimising the Dockerfile's shape; sometimes the right fix is remote cache, not a restructure. - **Reproducibility requirement.** If an auditor or an incident responder must rebuild an image from a tag six months later, option A (or B with digest pins) is the only comfortable answer. - **Ownership.** Option B only works with a team that owns the builder image. Without one it rots and every service is stuck on a stale toolchain. - **Context size.** Monorepos push large build contexts to the builder; keeping the transferred context tight is a separate concern but strongly shapes whether option A is even pleasant. - **Blast radius.** A shared builder is one compromise away from every service; self-contained builds spread that risk but multiply the patching work. - **Runtime base is orthogonal.** Whatever you pick, standardising the *runtime* stage — one minimal, non-root, centrally patched base per language — is usually the higher-value standardisation and is compatible with all three options. ## How to answer Don't pick a winner unprompted. State the axes — reproducibility, cold-build cost, ownership, blast radius, local parity — then commit: for most mid-size fleets, self-contained multi-stage Dockerfiles with a standardised runtime base, moving to a shared digest-pinned builder image once one language dominates and build minutes become a line item.