Docker Build Secret Rotation: Cache Validity, Execution Freshness, and Artifact Acceptance

Understand what a successful build proves

Rotating a secret supplied to a Docker build does not, by itself, prove that the build used the new value. If the relevant instruction can reuse a cached result, a successful build can export an artifact produced before the rotation. A release decision therefore needs evidence about the requested input revision, the relevant instruction, and the exported bytes.

Docker documents this behavior in its build cache invalidation rules: secret contents do not invalidate the cache, while properties such as the secret ID and mount path participate in its checksum. When fresh execution is required, a separate public build argument or an explicit cache bypass can make that requirement visible.

This playbook uses a small synthetic experiment for DevOps and platform engineers. Two public selectors, fixture-a and fixture-b, choose between two text artifacts. The result is exported to the client filesystem and inspected without starting it as a container. No production credential is required.

Use four explicit outcomes: ACCEPT a particular artifact for its declared input revision after checking the evidence; REBUILD when the policy requires fresh execution that has not yet been established; REJECT an export demonstrated to be stale; and HOLD when the environment, execution, sources, or output cannot be explained. These are the release-policy categories used in this playbook, not native Docker statuses.

The six-build sequence includes two negative controls. With the relevant cache retained and all other cache inputs controlled, case B is expected to reuse artifact-A after the selector changes to fixture-b. Case D reverses the direction and is expected to reuse artifact-B after the selector returns to fixture-a. The other cases establish a baseline or deliberately bypass the relevant cache.

The A–F outputs below are expected results derived from the documented behavior and the stated setup. They are not reported Docker measurements. The example gives a Dockerfile, an invocation pattern, and the checks needed to qualify an actual run on your builder.

Define the scope and documented behavior

The operational question is whether a build instruction that depends on a BuildKit secret has produced an artifact acceptable for the declared input revision. Keep that question separate from cache access rights, container configuration, runtime filesystem visibility, and remote credential revocation.

For example, GitHub Actions cache permissions concern who can restore or save workflow cache entries. Compose variable provenance concerns which configuration input determines a container variable. Those are useful adjacent investigations, but neither answers whether this BuildKit RUN consumed a rotated secret.

How secret mounts interact with cache reuse

Docker’s build secrets guide describes a secret mount as a temporary way to expose a value to a build instruction. In this Linux fixture, secret ID selector is mounted at /run/secrets/selector. Real credentials should travel through an appropriate secret mechanism rather than Dockerfile ARG or ENV values, which can expose them through image metadata, history, or provenance.

The Dockerfile secret-mount reference defines required=true as an error when a secret is unavailable to an executing instruction. It does not force the instruction to execute, invalidate a compatible cached result, or prove that the current value was read. Secret availability and instruction freshness are separate checks.

The mounted value can change while the previous result remains reusable. Changing the secret ID or its mount path would alter another cache input and undermine an experiment intended to isolate the effect of changing only the secret contents. Keep both fixed throughout the six cases.

Why the build exit status is insufficient

A zero exit status reports that the requested build completed successfully. It does not provide an instruction-by-instruction execution record. A cached RUN can coexist with later work in the same build, including copying or exporting its result.

Consider the synthetic dependency: selector A is read, artifact-A is written, and that instruction result becomes reusable. A later request supplies selector B, but a cache hit can return the earlier artifact-A without repeating the selection command. The result is compatible with the cache rules and incompatible with a release contract that requires the B artifact.

Acceptance therefore attaches to a specific combination of artifact bytes, declared selector revision, public freshness control, source revision, builder and worker identity, base image, target platform, and execution evidence. This is a proposed qualification policy. It is not a claim that Docker defines a universal release-acceptance standard.

Record the versions that actually run

Buildx is the client-side build interface and BuildKit performs the build work. Record both instead of assuming that a client version identifies the server. As a dated example, the September 14, 2026 Build Cloud release notes list BuildKit v0.33.0 for cloud builders and verification against Buildx v0.37.0. These are facts about that release, not prescribed versions for this fixture.

Keep the Dockerfile frontend stable as well. Without a syntax directive, the example uses the frontend bundled with the selected BuildKit installation. If you add a separately selected frontend, record its resolved identity and keep it unchanged across the sequence. Do not describe secret-value cache reuse as a newly introduced feature merely because a recent release documents related build changes.

Run a controlled six-build experiment

Use a sandbox builder that you own and can keep stable for the experiment. Prefer a controlled single-node builder so that the same worker and cache serve all six builds. Run the cases sequentially. Keep the Dockerfile, base digest, target platform, secret ID, mount path, frontend, and other build inputs unchanged. Do not prune, import another cache, or allow another experiment to populate the same cache keys between cases.

Use a separate directory containing only the Dockerfile as the build context. Keep the selector file and evidence files outside it. Give every case a new export destination. Choose a fresh public run identifier and derive two epoch values from it, such as that identifier followed by -e1 and -e2. In the table, e1 and e2 are shorthand for those distinct, run-specific values.

Define the synthetic artifact contract

Select an approved Linux base by its real repository and digest. It must support linux/amd64, provide /bin/sh, cat, and mkdir, and support shell case, printf, and test. Require no inherited ONBUILD triggers, no inherited ENV CACHE_EPOCH, and no existing /out path. The selected build user must be able to read the mounted file and create the output.

Save the following as the Dockerfile. It makes the user and shell explicit, checks the public epoch before producing output, and checks the secret read before dispatching on its value. The plain mkdir /out deliberately fails if that path already exists. These conditions keep inherited base-image behavior from silently changing the fixture.

ARG BASE_IMAGE
FROM ${BASE_IMAGE} AS select
USER 0
SHELL ["/bin/sh", "-c"]
ARG CACHE_EPOCH
RUN --mount=type=secret,id=selector,required=true \
    test -n "$CACHE_EPOCH" && \
    mkdir /out && \
    fixture_selector="$(cat /run/secrets/selector)" && \
    case "$fixture_selector" in \
      fixture-a) printf 'artifact-A\n' > /out/selection.txt ;; \
      fixture-b) printf 'artifact-B\n' > /out/selection.txt ;; \
      *) exit 41 ;; \
    esac
FROM scratch AS export
COPY --from=select /out/ /

The selectors are public sentinels, not authentication tokens. The command makes no request to an authorization service. Base-image or frontend resolution may still contact a registry, so the entire build should not be described as offline.

The final stage copies the complete output directory into a scratch filesystem. This follows Docker’s multi-stage artifact-copying model and keeps the select stage in the dependency graph of the export target. Checking the whole exported tree remains necessary; copying only the named file would conceal additional output files.

Execute the six cases in order

The expected sequence assumes the A result remains available for B and the C result remains available for D. Case C also requires an epoch value whose relevant result has not already been populated. Keep the run identifier unique and the worker state controlled; literal values reused across repeated experiments weaken that assumption.

Each byte string denotes the ten ASCII characters artifact-A or artifact-B followed by one LF byte, for 11 bytes in total. The notation \n represents that newline; it is not two characters to append to the file.

Before case A, assign BUILDER to the reviewed builder name, BASE_IMAGE to the approved digest reference, and CONTEXT_DIR to the Dockerfile directory. Set EPOCH to the run-specific e1 value and write fixture-a to SELECTOR_FILE. Use absolute paths without commas for these CSV-style option values. EXPORT_DIR must be a new case-specific destination; METADATA_FILE must be outside it, in an existing writable evidence directory.

A baseline invocation has this form. Shell :? expansions reject unset or empty required variables. Capture the command, exit status, stdout, and stderr with your runner; a wrapper must preserve the build command’s failure status.

docker buildx build \
  --builder "${BUILDER:?}" \
  --platform linux/amd64 \
  --target export \
  --network none \
  --build-arg "BASE_IMAGE=${BASE_IMAGE:?}" \
  --build-arg "CACHE_EPOCH=${EPOCH:?}" \
  --secret "id=selector,src=${SELECTOR_FILE:?}" \
  --no-cache-filter select \
  --provenance=false --sbom=false \
  --progress plain \
  --metadata-file "${METADATA_FILE:?}" \
  --output "type=local,dest=${EXPORT_DIR:?},platform-split=false" \
  "${CONTEXT_DIR:?}"

For B, C, and D, omit --no-cache-filter select. Use it again for E. For F, replace it with --no-cache. Change the selector and epoch only as specified in the table, and change the export and evidence paths for every case. Keep all remaining options fixed. The Buildx build reference documents the builder, target, platform, network, secret, progress, metadata, and cache-control options used here.

A followed by B tests reuse after A changes to B. C followed by D tests reuse after B changes back to A under the second epoch. This symmetry helps distinguish a cache explanation from a mistake specific to one selector. It does not replace inspection of the relevant RUN’s progress record.

Use a public epoch deliberately

The epoch represents an approved freshness decision. A release identifier or an independently managed input-revision identifier is suitable when it is public and changed whenever the policy requires recomputation. Do not put the credential, a credential hash, or a token prefix into it. Even a derived value can disclose information that does not belong in build arguments or provenance.

Declare ARG CACHE_EPOCH in the stage before the relevant RUN. Docker’s argument caching rules place the cache effect at use, including the implicit environment use of an ARG by following RUN instructions. An ENV value with the same name can override it, which is why this fixture excludes an inherited ENV CACHE_EPOCH.

The nonempty test makes the intended dependency visible and catches a missing value. It does not establish that the value is new. Freshness governance must ensure that a required new computation is not assigned an epoch already associated with an eligible cached result.

Choose targeted or broader cache bypass

A targeted bypass does not promise that every other stage stays cached; changed dependencies can affect later work. Conversely, a broader bypass does not execute unrelated stages that are outside the selected target’s dependency graph. Preserve the relationship between the target and the secret-dependent instruction when refactoring the Dockerfile.

Neither option establishes the business freshness of a response from a remote service. It also does not clear an application’s persistent cache mount. Docker’s base-image refresh guidance distinguishes --no-cache from --pull: ignoring instruction cache does not itself pull a fresh base image. This experiment intentionally keeps the approved base digest fixed.

Inspect the exported tree and exact bytes

Docker’s local exporter documentation describes writing the build result filesystem to the client. The invocation selects one platform and explicitly requests a flat destination. The artifact contract permits exactly one regular, non-symlink file at selection.txt in that destination, with the expected 11 bytes.

Attestation settings are part of that contract. Docker explains that local attestation exports can add JSON files at the export root. Keep --provenance=false --sbom=false fixed for this one-file experiment, and keep build metadata outside the artifact directory. If a later workflow requires attestations, define and validate that expanded tree explicitly.

1. Enumerate the complete export tree and reject an unexplained extra path.

2. Check the file type without following a symbolic link; a file that resolves to another location does not satisfy this fixture.

3. Compare exact bytes, including the terminal LF. File existence or size alone cannot distinguish artifact-A from artifact-B.

4. Preserve the exported file and progress evidence together. Do not overwrite an earlier case with a later result.

A local export is evidence about build output. It is not a test of a started container, a registry tag, a bind mount, or a deployed application. Keep those acceptance checks separate when the artifact later enters a runtime environment.

Collect evidence and make the release decision

Assign the three responsibilities

Separate the declaration of the required input, the construction of the build, and the acceptance of the artifact. These responsibilities can belong to different people or to independently reviewed automation, but their evidence should remain distinguishable.

Buildx, BuildKit, the base-image provider, and the CI runner contribute technical evidence. The ACCEPT decision remains a policy decision about a specific candidate. This ownership model fits within DevOps lifecycle management, where planning, delivery, and operational feedback are connected but perform different jobs.

Keep a minimum evidence ledger

Capture the following information for an actual run. Preserve stable environment information once and reference it from every case, while recording case-specific commands, outputs, and decisions separately.

The builder inspection command can bootstrap the builder; with the docker-container driver, that can start its BuildKit container. Treat it as a deliberate preparation step on the owned sandbox. A builder name is not sufficient if its nodes or endpoints can change during the experiment.

Buildx writes --metadata-file as JSON and requires its parent directory to exist and be writable. The available keys depend on the result and configuration. Do not demand an image digest from a local filesystem export simply because an image-export example shows one.

Review the progress entry for the secret-dependent RUN itself. A CACHED label elsewhere in the log, or evidence that COPY or export completed, cannot establish that RUN’s state. Matching output bytes and attributing them to a particular cache hit are separate checks.

Apply the decision matrix

If the expected sequence is reproduced, B and D are successful negative controls and failed release candidates for their requested selectors. The experiment deliberately asks for a result that can expose stale reuse. Its success does not authorize the stale artifact.

A, C, E, and F are candidates rather than automatic approvals. Their expected bytes must still agree with the actual export and the evidence required by the freshness policy. In production, a policy may explicitly permit reuse; the reviewer must know which policy applies before interpreting a cache hit.

Treat an unexpected cache miss as inconclusive

Suppose B produces artifact-B when the experiment expected reuse of artifact-A. That output alone does not show that changing a secret invalidated the cache. The relevant cache entry may have disappeared, the build may have reached another worker, or another input may have changed.

5. Compare the builder, node, endpoint, base digest, and frontend with the baseline.

6. Check for pruning, garbage collection, imported cache changes, and concurrent activity.

7. Compare the exact Dockerfile, invocation, epoch, and consumed inputs.

8. Locate the intended RUN in the log and determine whether the planned reuse was actually exercised.

Until those checks explain the difference, mark the cache demonstration inconclusive and HOLD its qualification. Failure to reproduce a cache hit is not proof of the opposite cache rule. Docker’s documented secret-value behavior is conditional on a compatible cached result being available for reuse.

Control the risks that can invalidate the experiment

Separate expected and measured results

The matrix is an oracle for a future or locally performed experiment. It should be compared with a separately captured observation, not copied into a results ledger as if it had been measured. An observation requires the actual command, identifiable environment, completion status, progress record, and exported artifact.

Once you run A–F, report that run’s versions and conditions. A successful shell check can establish the selector command’s behavior in that shell; it cannot establish BuildKit secret mounting, cache retention, worker selection, or exporter behavior. The larger conclusion requires evidence from those actual components.

Choose an approved base and preserve its identity

Obtain a real digest reference from your approved image catalogue. A tag such as alpine:latest does not satisfy the fixed-base contract. Conversely, finding a digest does not make the image approved: approval is an organizational decision about that specific image and its intended use.

The base-image pinning guidance explains why a digest is useful for fixing the image identity. Retain the repository, digest, requested platform, and resolved platform information together. A multi-platform reference and a platform-specific image digest describe different levels of selection, so keep the actual values your tooling reports.

Check the base assumptions before the sequence. An inherited ENV value can mask the public epoch, and inherited ONBUILD instructions execute as the base is consumed. The explicit USER and SHELL lines occur after FROM and do not neutralize ONBUILD. The fixture deliberately treats an existing /out path as a setup failure instead of silently merging inherited files into the output.

Preserve the intended cache state

The A/B and C/D controls depend on retained results. Docker’s garbage-collection documentation describes periodic pruning according to cache policies, including size and age. A stable builder name therefore does not prove that the relevant instruction result is still present.

Use a controlled cache and record relevant lifecycle events. Avoid global pruning as a repair for this experiment: it removes the very state needed for the negative controls and can disturb unrelated work. A cache bypass is an instruction-execution policy; cache deletion is a separate operation.

If a result is evicted at the wrong time, preserve the run as inconclusive and restart a fresh sequence under a new public run identifier once the cause is understood. Do not combine A from one environment and B from another and describe them as a controlled pair.

Handle timeouts as incomplete evidence

Treat a client timeout as HOLD. It leaves the intended observation incomplete: the reviewer cannot infer complete build termination, successful export, or a usable artifact merely from the fact that the client stopped waiting.

Keep partial output, the invocation, timestamps, and the case directory. Confirm the builder’s state through the available operational controls before retrying. Use a new destination for a retry so that partially written files cannot be mistaken for a complete later export. Classify the retry as a new observation.

Detect source drift without overclaiming its effect

Keep the context minimal and compare the exact Dockerfile bytes before and after each case. The selector file remains outside the context and is supplied through the secret option. Record any separately selected frontend as another input that must stay stable.

Docker’s build context documentation explains which source material is available to the build. An added but unused context file does not, by itself, prove that this RUN was invalidated. A changed instruction or consumed input can affect the experiment, so investigate the actual dependency rather than attributing every filesystem change to cache invalidation.

A source mismatch breaks the controlled comparison even if the resulting artifact looks correct. Hold the sequence until the reviewed source has been restored or the changed design has been deliberately requalified.

Keep synthetic selectors separate from real credentials

The two public sentinels make the selected branch observable without exposing a credential. They do not test whether a GitHub, AWS, npm, or other service accepts a rotated token. They also do not establish that an old credential has been revoked in every environment.

Secret mounts protect the transport boundary described by Docker; they do not prevent the command that receives a secret from printing it, copying it, or incorporating it into another output. For a real build, review that command and its logs as well as the mount configuration. In this fixture, only the public artifact marker is written.

If a reproduced run matches the expected sequence, its conclusion concerns the inspected build calculation under the recorded conditions. Test remote authentication and revocation separately, with the relevant service’s own evidence and an appropriate non-destructive procedure.

Keep export evidence separate from runtime evidence

The local exporter writes a build filesystem to a client directory. It does not start the resulting image or show the filesystem a deployed container will see. Refonte’s guide to files hidden by runtime bind mounts examines that later boundary: a runtime mount can change the visible view of files that exist in an image.

Accepting the synthetic selection file closes this fixture’s output contract. It does not close registry promotion, runtime configuration, mount, or deployment checks. Give each later boundary its own evidence instead of extending the meaning of the build’s success status.

Apply the policy in a delivery pipeline

Compare the available freshness policies

Prefer an explicit, reviewable choice over an implicit assumption about rotation. A public epoch is useful when freshness requirements follow a known release or input revision. A stage bypass is useful when the build owner can identify the exact work to repeat. A broader bypass can help isolate a problem, but should not be mistaken for a complete freshness guarantee.

Make the CI contract explicit

The input owner declares a public selector-revision identifier. The build owner maps that declaration to the required epoch or cache policy. The pipeline preserves exact inputs and uses a new export destination. The release reviewer checks the candidate against the declared contract and its actual evidence.

Bind the acceptance record to the builder and worker, base digest, source and frontend revision, selector revision, epoch, cache policy, artifact bytes, and reviewed evidence. A green job status can be one field in that record, but it should not replace the record.

Review the policy whenever the Dockerfile is reorganized. Renaming select, moving the RUN, changing the secret ID or target path, introducing cache mounts, or altering the output layout changes the assumptions of the control. Refonte’s discussion of broader DevOps pipeline design provides context for integrating such a gate into delivery automation; the artifact-specific evidence remains a separate requirement.

Recover from a demonstrated stale export

9. Preserve the stale export and its original logs, invocation, and environment record.

10.         Exclude that export from release candidates; do not edit its contents to make the check pass.

11.         Reconfirm the approved source and the public identifier of the requested selector revision.

12.         Choose a new output destination and an approved public epoch or cache bypass.

13.         Run the controlled rebuild and preserve its separate evidence.

14.         Review the relevant RUN’s progress and compare the new export tree and exact bytes.

15.         Record a new decision for the new candidate, with the relationship to the rejected case retained.

Recovery creates a new candidate from known inputs. It does not retroactively make the rejected artifact acceptable. If the new result remains unexplained, keep the decision at HOLD and investigate before another release attempt.

Use a consistent CI decision sequence

Apply the following branches in order. They express the same four decisions whether implemented by a reviewer or by validated pipeline logic.

16.         If the builder, worker, base, source, or build completion is unknown, HOLD and preserve the evidence.

17.         Review the relevant RUN’s progress and the complete exported artifact. If the export is demonstrably stale for the requested selector, REJECT that candidate.

18.         If the result is unexpected or the evidence cannot explain it, HOLD even when the output superficially looks fresh.

19.         If the remaining candidate is understood but fresh execution is required and has not been established, REBUILD from the reviewed inputs into a new destination using an effective freshness control.

20.         If the artifact matches the declared selector and the required evidence is sufficient, ACCEPT that exact candidate for that exact revision.

Automate comparisons and review causality

Automation can capture the environment and argument vector, compare source bytes, allocate distinct destinations, enumerate the export tree, verify file types, compare exact bytes, parse metadata JSON, and classify command failures or timeouts. These are concrete checks with explicit inputs and outputs.

Keep the byte comparison separate from the interpretation of cache behavior. A useful intermediate status is OUTPUT_SEQUENCE_MATCH; REVIEW_STAGE_LOGS: it says the exported sequence matches the oracle while leaving the stage-level attribution open. It is an example status for your workflow, not a claimed output from an existing driver.

Buildx documents plain and JSON progress modes, including --progress=rawjson for solve-status events as JSON lines. A parser can help correlate events with the relevant operation, but it needs validation against the versions and structures you support. Until that logic is qualified, review the stage record directly rather than turning a matching file into an automatic causal conclusion.

Build the broader engineering skills

For structured study of the surrounding practices, explore Refonte Learning’s DevOps Engineering Program. Its published curriculum includes Linux and scripting, Git and GitHub, CI/CD, Docker and Kubernetes, infrastructure as code with Terraform, cloud platforms, and monitoring. The programme page lists a three-month format at 12–14 hours per week, with an admission requirement of working toward a bachelor’s or higher-level degree. It also advertises a Training Certificate and a Certificate of Internship on successful completion.

Qualify and maintain the workflow

The cache rule is documented; the behavior of your selected environment still needs qualification. Treat the six cases as a controlled experiment with versioned inputs and dated observations. Once the workflow is established, preserve enough evidence to repeat it after changes to the builder, frontend, source, or release policy.

Create an actual record for every case

An actual qualification run should retain the environment record, exact Dockerfile, each case’s argument vector and exit status, plain progress output, metadata JSON, full export inventory, selection bytes, and final decision. Store the evidence where its integrity and retention match your release process. Keep metadata and logs outside the one-file artifact destinations.

Matching all six files is only one part of qualification. Confirm that the logs support the intended reuse in B and D and the required computation in A, C, E, and F. Any disagreement between output, source, command, and stage evidence needs an explanation before the sequence can support a release policy.

Cover the environments the organization supports

Repeat the protocol on the Docker, Buildx, BuildKit, and frontend combinations your organization actually supports. If several configurations are in use, record a distinct result for each. Do not infer universal behavior from one machine or prescribe an arbitrary number of versions as a substitute for the deployed inventory.

For each combination, ask whether the controlled sequence remains interpretable and whether the evidence capture still identifies the relevant RUN. A tool upgrade may change progress formatting or available metadata even when the documented secret-value cache rule remains the same.

Keep the missing-secret control separate

To test the mount requirement, use a separate case that omits the selector secret while forcing the select stage to execute, for example with --no-cache-filter select. Keep the base, source, and other prerequisites valid. The required secret-mount option should then produce an error attributable to the unavailable secret.

A nonzero status caused by an unreachable builder, failed base pull, unsupported option, or unwritable metadata directory is not a successful missing-secret test. Inspect the cause. Run this check outside the A–F sequence so that it does not confuse the cache-retention experiment or its evidence.

Track cache availability without changing it

Where supported operational tooling permits, record cache and worker lifecycle information before the intended negative controls. The aim is to detect eviction or movement of work, not to modify the cache to force an apparent pass. A listing that shows some cache records is not automatically proof that the exact required result remains reusable.

Do not base acceptance on an undocumented private API or an unqualified log parser. If a control depends on a version-specific interface, record and validate that dependency. Unexpected garbage collection or worker changes should make the controlled pair inconclusive rather than silently change its expected outcome.

Keep provenance tied to the artifact contract

Build metadata can supplement the release record, but it does not replace file inspection. Buildx’s metadata provenance can be configured separately through BUILDX_METADATA_PROVENANCE. Record the actual setting and the data returned. Do not assume that disabling exported attestations removes every provenance-related field from the separate metadata file.

An organization can define a release record using the following fields. These are proposed evidence requirements, not a Docker-defined acceptance schema or an example of measurements already collected.

When a secret-dependent result must be recomputed, declare that requirement through a public freshness input or a reviewed cache bypass. Then qualify the exported artifact for the requested revision. Cache compatibility, execution freshness, and artifact acceptance remain separate conclusions, each supported by its own evidence.