Invalidate Docker build cache deliberately after a build-secret change

Rotating a build credential does not necessarily rerun the instruction that consumes it.

Source facts

Docker states that secret contents do not participate in the build cache. Changing a secret value therefore does not invalidate a cached instruction. Secret identifiers and mount paths do affect the checksum. Docker documents using a separately changed build argument when intentional invalidation is required, without putting the secret value itself into that argument.

Source: Docker documentation — Build cache invalidation.

Applicability

Review cache invalidation for a Docker build instruction that consumes a changed secret.

DSE recommendation

DSE recommends deciding whether credential rotation should also force fresh access to the upstream service. If so, use a nonsensitive revision marker or the supported cache-control mechanism and keep that policy in the build definition. Do not expose the new credential as an argument merely to change a checksum. Separate a reproducible cached artifact from evidence that current authentication was exercised. Retain enough build metadata to explain whether the relevant instruction actually ran after rotation.

Verification

With a disposable secret and nonproduction build, compare a repeated cached build, a secret-value change, and an intentional cache-busting change. Observe which instruction executes without revealing credentials in output. Confirm the final artifact is correct and that the documented rotation acceptance test checks fresh authentication when required. Retain the nonsensitive cache-bust marker and execution evidence with the rotation record. Ask the build owner to state whether fresh upstream authentication is an acceptance requirement, then check that specific instruction instead of treating overall build success as proof.

Official reference

Docker documentation — Build cache invalidation. Reviewed October 20, 2026.