crane-append

Push image based on a base image

$ crane append [[-b|--base]] [image_name]

$ crane append [[-f|--new_layer]] [layer_name1 layer_name2 ...]

$ crane append [[-t|--new_tag]] [tag_name]

$ crane append [[-o|--output]] [path/to/tarball]

$ crane append --oci-empty-base

$ crane append --set-base-image-annotations

$ crane append [[-h|--help]]

crane append [OPTIONS] IMAGE LAYER [LAYER ...]

--platform
    Override platform for appended layers, e.g. linux/amd64 or linux/arm64

--insecure
    Allow HTTP (insecure) connections to registries

--timeout
    Set operation timeout, e.g. 5m (default 2m)

-h, --help
    Display help for append command

The crane append command is a subcommand of the crane CLI tool from the Google Container Tools project. It enables appending one or more layers to an existing OCI-compliant container image in a remote registry without requiring a full rebuild or daemon.

Specify the target IMAGE reference first, followed by layer sources. Layers can be local directories (built into tar layers), local tarballs, or remote layer references (e.g., registry/image@sha256:digest or plain digests). Crane fetches the base image manifest, appends the new layers in order, updates the config if needed, and pushes the modified image.

Key use cases include adding runtime dependencies, security updates, or custom files in CI/CD pipelines. It supports multi-platform images via --platform and handles compression automatically. No local image storage is needed, making it efficient for cloud-native workflows.

Requires push access to the target repository. Layers are appended sequentially, so order affects the final image filesystem.

Push permissions required for IMAGE repository.
Layer order is preserved; test compatibility.
Remote layers must be publicly accessible or authenticated.
Not for production base image mutation; prefer immutable tags.

Local: ./dir or layer.tar.
Remote: ghcr.io/user/img@sha256:abc... or sha256:abc... (fetches from index)

crane append ghcr.io/user/myimg:v1 ./overlay-dir
crane append myreg/img --platform linux/arm64 layer.tar digestlayer

Developed by Google Container Tools starting 2021 as a daemonless OCI tool. Append subcommand introduced in early releases (~v0.5) to enable lightweight image extension, integrated with Sigstore for signing.

crane(1), skopeo(1), regctl(1), docker-push(1)