What does setting SOURCE_DATE_EPOCH change about a BuildKit container image build?

### The problem it solves Two of the reasons a rebuilt image gets a new digest are pure clock readings. The image config has a `created` field, each entry of its `history` array has one, and every file written into a layer carries an mtime in the layer's tar stream. Build the same source twice, five minutes apart, on a cold cache, and all of those move - even when not one byte of application content changed. `SOURCE_DATE_EPOCH` exists to take the clock out of the build. ### What it is `SOURCE_DATE_EPOCH` is a cross-ecosystem convention, not a Docker invention: a Unix timestamp, in seconds, that a build tool should use anywhere it would otherwise read the current time. BuildKit implements it. When it is set, the builder writes that value into the image config's `created` field and into the `history` entries, and it normalises the timestamps of files in the layers the build produces, instead of stamping them with the moment of the build. The usual value is the timestamp of the commit being built, which is stable for a given source revision and is trivially derived in the pipeline: ``` export SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct) ``` `docker buildx build` picks the variable up from the environment; it can also be passed explicitly as a build argument (`--build-arg SOURCE_DATE_EPOCH=...`), which is the form to use when the value must cross into a builder that does not share your shell environment. ### What it does not do This is the half candidates miss, and it is the half that matters in an interview. It does not pin any input. `FROM eclipse-temurin:21-jre-noble` still resolves a mutable tag; `apt-get install` still installs whatever the mirror serves today; a `curl` of a tarball still fetches today's file. Those change layer *content*, and no amount of timestamp normalisation makes a different jar into the same jar. `SOURCE_DATE_EPOCH` removes one family of variance and leaves the other three - unpinned inputs, injected build metadata, and genuinely non-deterministic build steps - untouched. It does not retroactively fix layers that come from somewhere else. Base image layers keep the timestamps their own publisher gave them; the value applies to what this build creates. And it interacts awkwardly with the build cache. A layer reused from cache was materialised earlier, under whatever epoch was in effect then, and a cached reuse can therefore carry timestamps that do not match the epoch you set for this run. The practical consequences are that a reproducibility check should build with `--no-cache` (or a cache-free builder) rather than trusting a warm cache, and that a mixed warm/cold pipeline can produce two "reproducible" builds that still disagree. Newer BuildKit releases add an exporter attribute to rewrite timestamps on cached layers as well, which narrows the gap; treat the availability of that as version-dependent and verify on the builder you actually run. ### Where it sits in the sequence Think of reproducibility as layers of an onion. `SOURCE_DATE_EPOCH` is the outermost and cheapest: one exported variable, no change to what the image contains, and it eliminates the noise that otherwise makes every rebuild differ. Underneath it sit the expensive properties - a digest-pinned base, locked dependency versions, checksum-verified downloads, a build that does not touch the network at all. Setting the epoch first is still worth doing, because until the clock is out of the way you cannot tell a real content change from ordinary timestamp churn: every rebuild differs, so no difference is informative. ### A worked check For a Spring Boot fraud-scoring service whose dependency layer is 2.3 GB, the useful experiment is: ``` export SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct) docker buildx build --no-cache --load -t fraud-scoring:r1 . docker buildx build --no-cache --load -t fraud-scoring:r2 . docker image inspect --format '{{.Id}}' fraud-scoring:r1 fraud-scoring:r2 ``` If the two IDs match, the build is deterministic on this machine at this moment - which is a much weaker statement than "reproducible", because both runs saw the same package mirror seconds apart. If they differ, the epoch has already done its job: whatever is left is real, and worth chasing. ### Interview framing The candidates who impress do three things: they define the variable rather than reciting it, they set it from the commit timestamp rather than from `date`, and they immediately name the limits - unpinned inputs and cached layers - instead of presenting it as the answer to reproducibility. The ones who do not usually assert that setting it makes builds reproducible, full stop.