docker buildx replay build
| Description | Rebuild an image from provenance and pinned materials |
|---|---|
| Usage | docker buildx replay build [OPTIONS] SUBJECT |
Experimental
This command is experimental.
Experimental features are intended for testing and feedback as their functionality or design may change between releases without warning or can be removed entirely in a future release.
Description
replay build reconstructs an image from the provenance attestation attached
to an existing subject.
The replay mode controls how sources are resolved:
materials(default) pins every source to the digest recorded in the provenance. A source that is not recorded, or whose content changed, fails the build.frontendreplays the recorded frontend and options, but resolves sources again, so the result can differ from the original build.
Replayed builds do not add new provenance or SBOM attestations. Local outputs
with mode=delete are not supported.
Options
| Option | Default | Description |
|---|---|---|
--dry-run | Print a plan of the replay without solving or exporting | |
--format | pretty | Format dry-run output (pretty | json) |
--load | Shorthand for --output=type=docker | |
--network | Network mode for RUN instructions (default | none; defaults to the mode of the original build) | |
-o, --output | Output destination (format: type=local,dest=path) | |
--platform | Platform of the subject to replay (defaults to the only platform of the subject or the builder default platform) | |
--progress | auto | Set type of progress output (auto | plain | tty | quiet | rawjson) |
--push | Shorthand for --output=type=registry,unpack=false | |
--replay-mode | materials | Replay mode (materials | frontend) |
--secret | Secret to expose to the replayed build (format: id=mysecret[,src=/local/secret]) | |
--ssh | SSH agent socket or keys to expose (format: default|<id>[=<socket>|<key>[,<key>]]) | |
-t, --tag | Image identifier (format: [registry/]repository[:tag]) |
Examples
Replay a registry image and export to an OCI tar
docker buildx replay build docker-image://example.com/app@sha256:deadbeef \
--output=type=oci,dest=replay.oci.tar
Dry-run a replay to inspect the plan
docker buildx replay build docker-image://example.com/app@sha256:deadbeef --dry-run --format=json | jq
Dry-run runs the same checks as a real replay, so a subject that cannot be replayed fails before any build starts.