# crane append: Add a Layer Without a Dockerfile

> crane append adds a tarball as a new layer on top of a base image and pushes the result, no Dockerfile or daemon needed. Reference for -f, -b, -t, and CI errors.

Source: https://latchkey.dev/learn/command-reference/crane-append-layer  
Updated: 2026-06-30

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.

## FAQ

### 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.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt