Container builds are usually treated as something that happens once: the source code is checked out, Docker Buildx creates an image, the image is pushed to a registry, and the deployment pipeline moves on.
The problem appears later when a team needs to reproduce an older build.
A production image may have been created several weeks ago. The source repository has moved forward, dependencies have changed, and the build environment is no longer identical. Rebuilding the image from the current Dockerfile may produce a different result.
Docker Buildx Replay addresses this problem by using the provenance recorded with an existing build. Instead of asking developers to reconstruct the original build command manually, Buildx can use the recorded frontend, options, source information, and pinned materials to reproduce the build.
The feature is currently experimental and requires BuildKit v0.27 or later. It is intended for testing and scenarios where reproducing or verifying historical builds matters.
What Is Docker Buildx Replay?
Docker Buildx Replay is an experimental Buildx capability that reconstructs a container image from the provenance attached to an existing build.
A normal Buildx build might look like this:
docker buildx build \
--platform linux/amd64 \
--provenance=mode=max \
-t example.com/myapp:1.0 \
--push .
The important part for replay is the provenance.
Provenance can contain information about the build process, including the frontend, build options, and source materials used to create the image. Buildx Replay uses this information instead of relying only on the current Dockerfile and repository state.
A replay can start from an image reference, an OCI layout, or a local provenance attestation file.
Why Reproduce an Earlier Container Build?
Reproducing an old build becomes useful when the exact origin of a production artifact needs to be investigated.
For example, suppose version 1.4.2 of an application was deployed six months ago.
Source commit
|
v
Docker Buildx
|
v
Image + provenance
|
v
Production
Later, a security team asks:
“Can you rebuild the same artifact from the recorded source materials?”
A normal rebuild may not be enough.
The repository may have changed. A base image tag may point somewhere else. A package dependency may have released a newer version. Even the build configuration may have evolved.
Replay provides a way to reconstruct the build using information recorded with the original artifact.
This is particularly useful for:
- Supply-chain investigations
- Reproducing production images
- Build verification
- Security audits
- Debugging historical releases
- Investigating differences between published artifacts
- Testing whether recorded provenance is sufficient for reproduction
How Buildx Replay Works
The basic workflow is:
Existing image
|
v
Provenance attestation
|
v
Recorded build information
|
v
Buildx Replay
|
v
Rebuilt image
The replay process reads the provenance associated with the subject and reconstructs the build using a selected BuildKit builder.
Buildx Replay supports two important replay modes:
materials
frontend
The default mode is materials.
In this mode, Buildx pins the sources to the digests recorded in provenance. If a required source is missing or its content has changed, the replay fails rather than silently using different content.
The frontend mode replays the recorded frontend and options but resolves sources again. Because the sources can be different, the resulting image may also be different.
Recording Sufficient Provenance
Replay depends heavily on the provenance generated during the original build.
A build using minimal provenance may not contain enough information for replay.
For replay scenarios, use:
docker buildx build \
--provenance=mode=max \
-t example.com/myapp:1.0 \
--push .
The mode=max setting records more complete build information than minimal provenance.
This matters because replay may require information such as build arguments, secrets, and SSH configuration used during the original build.
If the original build did not record sufficient provenance, Buildx cannot reconstruct information that was never captured.
Replaying an Image
A registry image can be used as the replay subject.
For example:
docker buildx replay build \
docker-image://example.com/myapp:1.0 \
--load
The --load option exports the rebuilt image to the local Docker image store.
You can also tag the replayed image:
docker buildx replay build \
docker-image://example.com/myapp:1.0 \
--load \
--tag myapp:replayed
For a CI pipeline, pushing the replayed image to a registry may be more appropriate:
docker buildx replay build \
docker-image://example.com/myapp:1.0 \
--push \
--tag example.com/myapp:replayed
The exact output should be chosen based on whether the goal is local investigation, testing, or publishing a rebuilt artifact.
Inspecting a Replay Before Running It
One useful option is --dry-run.
Instead of immediately executing the build:
docker buildx replay build \
docker-image://example.com/myapp:1.0 \
--dry-run
You can request JSON output:
docker buildx replay build \
docker-image://example.com/myapp:1.0 \
--dry-run \
--format=json
This is useful in CI pipelines because the replay plan can be inspected before resources are consumed.
For example, a pipeline can first validate whether the artifact contains enough information for replay:
Retrieve image
|
v
Read provenance
|
v
Dry-run replay
|
+---- Failed ----> Stop pipeline
|
v
Execute replay
Docker documents that the dry-run performs the same replay checks before an actual build begins.
Replay From a Specific Platform
Container images are often published for multiple platforms.
For example:
linux/amd64
linux/arm64
Replay can select the platform that needs to be reconstructed:
docker buildx replay build \
docker-image://example.com/myapp:1.0 \
--platform linux/amd64 \
--load
This is useful when investigating a platform-specific production issue.
Instead of rebuilding every architecture, the team can focus on the platform associated with the reported problem.
Replay From an OCI Layout
Replay is not limited to registry references.
An OCI layout can also be used as the subject:
docker buildx replay build \
oci-layout://./my-image \
--output=type=oci,dest=replayed-image.tar
This can be useful in environments where the original artifact is stored outside a traditional image registry.
It also provides another option for controlled build verification workflows.
Using Replay With Secrets and SSH
Some builds require private resources.
For example, a Dockerfile might use an SSH mount:
RUN --mount=type=ssh git clone [email protected]:company/private-repo.git
Or a build might require a secret:
RUN --mount=type=secret,id=npmrc \
npm install
Replay cannot magically recover credentials.
If the original build required secrets or SSH access, the required credentials need to be supplied during replay.
For example:
docker buildx replay build \
docker-image://example.com/myapp:1.0 \
--secret id=npmrc,src=$HOME/.npmrc \
--ssh default
This is an important operational distinction.
Provenance can describe how a build was performed, but it should not be treated as a replacement for secret management.
Never store passwords, tokens, or private keys directly inside a Dockerfile or provenance configuration simply to make replay easier.
Replay Mode: Materials vs Frontend
The choice between replay modes affects reproducibility.
| Replay mode | Source resolution | Reproducibility | Typical use |
|---|
materials | Uses recorded source digests | Higher | Reproducing historical builds |
frontend | Resolves sources again | Lower | Testing the recorded build configuration against current sources |
The default materials mode is generally the appropriate choice when the goal is to reproduce an earlier artifact.
For example:
docker buildx replay build \
docker-image://example.com/myapp:1.0 \
--replay-mode=materials \
--load
The important concept is that replay is not simply “run the Dockerfile again.”
It is an attempt to reconstruct the build using information associated with the original artifact.
What Builds Can Be Replayed?
Not every Buildx build is automatically replayable.
According to the current Buildx documentation, replay requires provenance captured with mode=max. The original build context also needs to have been a Git repository or an HTTP(S) URL.
Builds based on local directories, standard input, OCI layouts, or other unsupported context types cannot be replayed through this mechanism.
The recorded source materials must also still be available.
This means teams should think about replay when designing their build pipeline rather than after an incident occurs.
Common Problems When Replay Fails
Missing provenance information
The first issue is insufficient provenance.
If the original build was created with minimal provenance, required replay information may be missing.
Review the provenance configuration used by the original build.
For replay-oriented pipelines, consider:
--provenance=mode=max
Source material is unavailable
A replay can fail when the source recorded by provenance is no longer available.
For example, a Git repository, commit, or referenced material may no longer be accessible.
This is one reason source retention policies matter.
Unsupported build context
If the original build depended on a local directory context, replay may not have enough recorded material to reconstruct it.
Moving the build to a reproducible Git-based context can make future replay scenarios easier.
Missing secrets or SSH credentials
A replay may reach a build step that requires credentials.
The solution is not to modify the original image or provenance. Provide the required credentials through the supported Buildx options.
Different network behavior
Replay also has network considerations.
The command supports:
--network=default
or:
--network=none
When reproducing a build for investigation, explicitly controlling network access can make the result easier to reason about.
Best Practices for Production Build Pipelines
Generate complete provenance
If your organization cares about supply-chain verification or historical reproduction, provenance should be treated as part of the build output.
A typical Buildx build can use:
docker buildx build \
--provenance=mode=max \
-t example.com/myapp:$VERSION \
--push .
Use immutable source references
Tags are convenient, but they can move.
For reproducibility, builds should record immutable source information such as commit references and image digests wherever practical.
Keep source repositories available
Provenance cannot reproduce source material that has disappeared.
Retention policies should account for the lifetime of production artifacts.
Test replay in CI
Do not wait for a security incident to discover that an artifact cannot be replayed.
A CI job can periodically select a release image and run:
docker buildx replay build \
docker-image://example.com/myapp:$VERSION \
--dry-run
For higher assurance, execute the replay and compare the resulting artifact according to your verification process.
Keep replay credentials separate
Secrets required for replay should come from the CI secret manager or secure runtime configuration.
They should not become part of the Dockerfile or source repository.
When Should You Use Docker Buildx Replay?
Buildx Replay is most useful when the team needs evidence about how an existing image was produced.
Use it when:
- A production image needs to be reconstructed.
- A security team needs to investigate an artifact.
- You want to test the completeness of build provenance.
- You need to investigate whether source materials changed.
- You want a repeatable process for historical build analysis.
- Your organization is improving software supply-chain controls.
It is less useful for ordinary local development where rebuilding the current source is sufficient.
Because Replay is currently experimental, teams should evaluate it in CI and controlled environments before making it a critical dependency in their release process.
Advantages and Disadvantages
| Advantages | Disadvantages |
|---|
| Can reconstruct historical builds from provenance | Currently experimental |
| Reduces manual reconstruction of build commands | Requires sufficiently complete provenance |
| Supports registry and OCI-based subjects | Some original build contexts cannot be replayed |
| Supports platform-specific replay | Required source materials must remain available |
| Useful for supply-chain investigations | Secrets and SSH credentials still need to be supplied |
| Provides dry-run validation | Replay does not guarantee identical output in frontend mode |
Production Checklist
Before depending on Buildx Replay, verify the following:
- Buildx and BuildKit versions support Replay.
- The feature has been tested in your CI environment.
- Production builds generate sufficient provenance.
- Source repositories and required commits remain available.
- Base images and other important materials can be resolved as expected.
- Required secrets and SSH credentials are managed separately.
- Replay failures are visible in CI.
- Platform-specific images are tested when required.
- Replay is not confused with a normal Dockerfile rebuild.
- Experimental functionality is not treated as a guaranteed long-term interface.
Summary
Docker Buildx Replay provides a practical way to revisit an earlier container build using provenance recorded with the original artifact.
The important difference from a normal rebuild is that Replay uses information from the historical build rather than relying only on the current source tree and Dockerfile.
For the best reproducibility, the original build should generate complete provenance, use supported source contexts, and preserve the source materials required for reconstruction.
The materials replay mode is particularly useful when the goal is to reproduce an earlier build using the sources recorded with that build. The frontend mode is better suited to scenarios where the recorded build configuration needs to be replayed while resolving sources again.
As an experimental Buildx capability, Replay should be introduced carefully. A good starting point is to use dry runs and controlled CI jobs, verify that existing production artifacts are replayable, and only then consider integrating it into broader software supply-chain workflows.
Join the conversation! Your thoughts help the community grow.