igergov.com
← Writing
DevOpsDockerSecurity · 3 min · BG EN ES DE

Docker build secret cache: why is the step still CACHED?

Why changing a secret does not request a fresh build step. Docker build secret cache, CACHEBUST, --no-cache-filter and verification limits.

Imagine this case. A Docker build step downloads dependencies from a private package registry. You change the token supplied as a build secret. On the next build, the same step reports CACHED. All other cache inputs are unchanged. Was the new token used at all?

This is a hypothetical case, not a reproduced experiment. The explanation follows Docker documentation for BuildKit-backed builds, not the behaviour of every container-image builder. (docs.docker.com)

The value is not the identifier

Docker explicitly states that changing a build secret’s value does not invalidate the cache. Its identifier and mount path, however, participate in the cache checksum. Changes to other inputs can also cause re-execution. (docs.docker.com)

The engineering inference is narrow: CACHED does not establish that the new token was used. Reusing a result does not check current access permissions. This follows from excluding the secret value from the checksum. (docs.docker.com)

Delivering a secret does not request a rerun

With a secret mount, the client supplies the secret through –secret and the relevant RUN instruction consumes it through the mount. The secret is temporarily available during execution. This describes delivery, not a request to repeat the instruction. (docs.docker.com)

Do not move the token into a build argument or Dockerfile ENV to change the cache. Docker warns that these mechanisms are unsuitable for secrets. Argument values may remain in image metadata or history. (docs.docker.com)

Two ways to request re-execution

One approach is a separate, non-sensitive build argument such as CACHEBUST. Declare it as an ARG in the relevant stage before the corresponding RUN instruction. When changing the token, also change the revision supplied through –build-arg. Changing the argument’s value causes a cache miss at its first use, including implicit use by a subsequent RUN instruction, not at the ARG declaration itself. (docs.docker.com)

The other approach is –no-cache-filter. It specifies named stages whose build cache should be ignored. If dependency downloading belongs to a stage named install, select that stage. The filter accepts stage names, not secret identifiers. This chooses the scope of re-execution; it is not an authentication test. (docs.docker.com)

Mounting does not prevent every disclosure

BuildKit’s guide explicitly acknowledges that an executing build can read a mounted secret. Therefore, do not treat the mount as protection against a command that prints or copies the token. The linked document is on master: an evolving guide, not a specification for a pinned release. (github.com)

What to check next

Start with the purpose of the check. Must the dependency step simply run again, or must you establish that the registry accepts the new credential? For the latter, look for evidence of an actual authenticated request, without exposing the secret. Do not substitute the overall build status for that criterion.

For the broader Docker and CI context, see One app, ten problems. Here, the next diagnostic step is narrower. (igergov.com)

Which specific build stage actually needs to run again?

Sources