crane append lays a tarball on top of a base image as a new layer and pushes the resulting image, with no Dockerfile and no daemon.
For images that are just "a base plus a few files" (a static binary, some config) crane append builds them without a Dockerfile or a builder, which is fast and reproducible in CI.
What it does
crane append takes a base image (-b) and one or more layer tarballs (-f), creates a new image with those layers on top, and either pushes it to a tag (-t) or writes it to a tarball (-o). It is a minimal, deterministic way to produce an image from files.
Common usage
Terminal
# pack a binary into a tar, then append it onto a base
tar -cf app-layer.tar -C ./dist app
crane append \
-b gcr.io/distroless/static:nonroot \
-f app-layer.tar \
-t ghcr.io/acme/app:1.4.0
# write the result to a local tarball instead of pushing
crane append -b alpine:3.20 -f app-layer.tar -o image.tar
Options
Flag
What it does
-b, --base <ref>
Base image to append onto
-f, --new_layer <tar>
Tarball to add as a new layer (repeatable)
-t, --new_tag <ref>
Push the result to this reference
-o, --output <file>
Write the result to a tarball instead of pushing
--insecure
Allow HTTP / skip TLS verification
In CI
crane append is ideal for a static Go/Rust binary on a distroless base: build the binary, tar it, append it, and push, all without a Docker daemon or BuildKit. Because the inputs are fixed the output digest is stable across runs.
Common errors in CI
"UNAUTHORIZED: authentication required" pushing to -t means log in first. A layer that lands in the wrong place usually means the tar was created without the right -C base directory (paths inside the tar become paths inside the image). "MANIFEST_UNKNOWN" on -b means the base reference is wrong.
Frequently asked questions
crane append: Add a Layer Without a Dockerfile?
For images that are just "a base plus a few files" (a static binary, some config) crane append builds them without a Dockerfile or a builder, which is fast and reproducible in CI.
What it does?
crane append takes a base image (-b) and one or more layer tarballs (-f), creates a new image with those layers on top, and either pushes it to a tag (-t) or writes it to a tarball (-o). It is a minimal, deterministic way to produce an image from files.
In CI?
crane append is ideal for a static Go/Rust binary on a distroless base: build the binary, tar it, append it, and push, all without a Docker daemon or BuildKit. Because the inputs are fixed the output digest is stable across runs.
Common errors in CI?
"UNAUTHORIZED: authentication required" pushing to -t means log in first. A layer that lands in the wrong place usually means the tar was created without the right -C base directory (paths inside the tar become paths inside the image). "MANIFEST_UNKNOWN" on -b means the base reference is wrong.
