Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

rib — Rust Image Builder

rib is a rootless OCI image builder written in Rust. Its name references the project that inspired it, Jib. It packages prebuilt artifacts and runtime files without a Docker daemon, privileged containers, or commands executed inside the image being built.

rib creates reproducible COPY layers using file operations and publishes the result directly to a registry, an OCI archive, or a Docker archive.

When to use rib

Use rib when an application has already been built and you need to:

  • package a binary, a frontend, or another set of files as an OCI image;
  • build the image without root access or a container runtime;
  • integrate image packaging and signing into a CI/CD pipeline.

rib does not process Dockerfiles. If image preparation requires RUN or other Dockerfile-specific instructions, use a compatible builder such as BuildKit or Buildah.

rib can be installed directly in a build-environment image so Docker or Kubernetes can cache that image normally. Repeated builds do not require a mandatory full pull of the base image: its root filesystem is not unpacked unless the selected output requires it.

How to navigate this book

GoalChapter
Install rib and build the first imageGetting started
Understand the project’s scopePurpose and design principles
Learn about manifests, configs, layers, and digestsOCI image model
Configure a Rust projectCargo integration
Add image building and signing to GitLab CICI/CD, Docker, and Kubernetes
Configure caching, logs, timeouts, and concurrencyOperations
Review security propertiesReproducibility and security
Study rib internalsArchitecture
Check whether rib fits a particular use caseLimitations

For a first look, read Purpose and design principles and Getting started. The remaining chapters can be used as reference material when configuring a particular build scenario.

OCI image model

An OCI image is a collection of content-addressed objects connected by descriptors. rib creates those objects directly according to the OCI Image Specification, without a Docker daemon or a temporary container.

This chapter defines the terms layer, digest, manifest, and configuration used throughout the rest of this book.

Analogy: an image as filesystem patches

Start with an empty filesystem. Each layer is a set of changes applied to it: add a file, replace a file, or add a directory. Applying all layers in order produces the container filesystem, much like applying a sequence of Git commits produces a repository state.

rib does not implement every Dockerfile operation. It creates one kind of layer: take files from the host and place them at selected image paths. Such a layer is requested with --copy.

Descriptors and digests

Every layer, configuration, and manifest is identified by a SHA-256 hash of its own bytes. This hash is the object’s digest. Changing one byte changes the digest.

A descriptor is a small JSON value that specifies how to locate and verify an object:

{
  "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
  "digest": "sha256:def456...",
  "size": 28471122
}

The descriptor contains only the media type, size, and digest. The actual bytes are stored separately—by digest in a registry or under blobs/ in an OCI archive. This is content-addressable storage: location is derived from content. If two builds produce the same layer bytes, the registry sees the same digest and does not need a second upload.

Layer: a filesystem change

A layer is a tar archive describing a change relative to preceding layers. Layers are applied in manifest order, so a later layer can replace a path from an earlier one.

Every layer created from --copy is deterministic and gzip-compressed. It contains only explicitly selected files and directories. rib executes no container commands and computes no filesystem diff.

Multiple layers may be built concurrently, but rib restores command-line order before assembling the image. Completion order therefore never changes the image semantics or digest.

Configuration: how the container runs

The image configuration is JSON containing runtime metadata rather than file contents:

  • architecture, os, and optional variant identify the target platform;
  • config.Entrypoint, config.Cmd, and config.Env describe process startup;
  • config.WorkingDir and config.User set the working directory and user;
  • config.ExposedPorts and config.Labels declare ports and labels;
  • rootfs.diff_ids lists uncompressed layer identifiers in application order;
  • history records layer-producing and metadata-only operations;
  • created records the image creation time.

For a registry base image, rib clones the base configuration, appends layer and history data, sets created, and applies explicitly requested runtime metadata such as --entrypoint and --label. Other fields, including the base Env, are preserved; the current CLI does not modify Env.

For scratch, the configuration is created from nothing. The standalone CLI uses --platform or its linux/amd64 default; Cargo integration requires the platform through metadata or the CLI. Layer and history lists start empty. scratch is a special exact keyword, not an image stored in a registry.

Manifest: the table of contents for one image

A manifest connects one configuration with an ordered layer list:

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "config": {
    "mediaType": "application/vnd.oci.image.config.v1+json",
    "digest": "sha256:abc123...",
    "size": 1842
  },
  "layers": [
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "digest": "sha256:def456...",
      "size": 28471122
    }
  ]
}

One manifest describes one platform-specific image. A registry tag is a mutable reference to either a manifest digest or a multi-platform index. A manifest digest is immutable because it is calculated from the manifest bytes. For production, registry.example.com/app@sha256:... therefore identifies one result more reliably than a tag.

Image index: multiple platforms under one tag

An image index lists platform-specific manifest descriptors, allowing a client to select the appropriate image for linux/amd64, linux/arm64, and other platforms.

rib builds exactly one platform per invocation. When the base reference resolves to an index, it selects the manifest matching --platform. The output remains a platform-specific manifest, not a new multi-platform index. An OCI archive contains an index.json, but it has a single reference to the built manifest.

Why layers have both digest and diff_id

Each compressed layer has two SHA-256 identifiers:

diff_id = sha256(layer.tar)      — uncompressed content
digest  = sha256(layer.tar.gz)   — compressed bytes that are transferred

The same tar stream can be compressed by different tools or settings, changing the gzip bytes and digest while leaving diff_id unchanged. Consequently:

  • digest identifies the blob stored in registries and OCI archives and is written to manifest.layers[i].digest;
  • diff_id identifies the unpacked result and is written to config.rootfs.diff_ids[i].

Configurations and manifests are content-addressed in the same way:

config_digest   = sha256(config.json bytes)
manifest_digest = sha256(manifest.json bytes)

Changing metadata such as a label changes the configuration bytes, which changes its descriptor inside the manifest and therefore changes the final manifest digest. The final digest fingerprints the complete image, including metadata rather than filesystem contents alone.

An image is an immutable graph

tag ───────► manifest digest or image index digest
                  │
                  ├──► manifest ─► config descriptor ──► config JSON
                  │                    │
                  │                    └──► ordered layer descriptors
                  │                                      │
                  │                                      └──► compressed layer blobs
                  └──► image index ─► platform-specific manifest descriptors

Existing objects are never rewritten. A build creates a new graph root: rib reuses base-layer descriptors, appends new layers, and creates a new configuration and manifest while old blobs remain untouched.

The next chapters explain why this model is useful in rootless CI/CD and how it is implemented inside rib.

Purpose and design principles

rib handles the final stage of a build pipeline. Once an application has been compiled and tested, it packages the artifact and required runtime files as an image and publishes it to a registry or writes it to an archive.

source code
    │
    ▼
compile and test
    │
    ▼
artifact + runtime files
    │
    ▼
rib
    ├──► registry
    ├──► OCI archive
    └──► Docker archive

For Rust projects, cargo rib build first runs cargo build and then passes the resulting artifact into the common image pipeline. The standalone rib build command does not build the application itself.

Rootless builds through file operations

rib never starts a process inside the image being assembled. It creates new layers exclusively from files selected by --copy or [package.metadata.rib]. It only needs permission to read inputs, write temporary tar/gzip files, access the OCI Distribution API, and write a local archive when requested.

No Docker daemon, container runtime, overlay filesystem, mount namespace, Docker socket, or build container is required. Ownership and permissions in the resulting image are written directly into tar headers, so image-level chown does not require equivalent host privileges. This makes Docker and Kubernetes builds ordinary unprivileged workloads.

Working with a base image

Initially, rib fetches only the base manifest, configuration, and layer descriptors. It does not perform the equivalent of a full docker pull.

When publishing to a registry, OCI content addressing is used:

  1. a blob already present in the target repository is not uploaded again;
  2. repositories on the same registry use cross-repository mount when allowed;
  3. only a missing blob is downloaded from the source and uploaded to the target.

The registry remains both the source of truth and the store of reusable layers. OCI and Docker archives must contain every base layer and therefore download all of them. A registry output downloads only blobs that the target could not reuse.

Caching the build environment

CI jobs commonly run in Docker containers or Kubernetes pods. rib can be included directly in the build-environment image—for example, in a Node.js Alpine image containing the frontend toolchain. The runner’s container runtime caches this image normally, so later jobs start in an environment where the OS dependencies, Node.js, and rib are already available.

Application dependency caches such as node_modules, the Cargo registry, and target remain normal CI caches. rib build --cache stores only downloaded base-image blobs; it does not cache newly built COPY layers between runs.

Composition with signing systems

rib deliberately delegates signing to tools such as cosign. Human-readable progress and the final summary go to stderr. When stdout is redirected or used in command substitution, stdout contains only the manifest digest:

IMAGE_DIGEST="$(rib build ... --to registry:registry.example.com/team/app:v1)"
cosign sign "registry.example.com/team/app@${IMAGE_DIGEST}"

The script does not parse logs. The immutable digest can be passed directly to signing, attestation, or deployment tooling.

Deliberate boundaries

rib does not process Dockerfiles or execute arbitrary image commands. It does not support RUN, install packages while packaging, perform cross- compilation or emulation, infer Cargo artifacts or linkage, build a multi- platform index in one invocation, sign images, or generate SBOM/provenance.

Use a full Dockerfile-compatible builder when the final root filesystem must be modified through RUN. rib is intended for prepared files that need a rootless, reproducible, automation-friendly packaging stage.

Getting started

Installation

crates.io

Installing the published crate requires Rust 1.88 or later:

cargo install rust-image-builder --version 0.1.0 --locked

Omit --version to install the latest published version:

cargo install rust-image-builder --locked

Package page: rust-image-builder 0.1.0 on crates.io.

GitHub Releases

Prebuilt binaries do not require a Rust installation. Archives and checksum files are available from GitHub release v0.1.0.

Example for Linux x86_64 with glibc:

version=v0.1.0
archive="rib-${version}-x86_64-unknown-linux-gnu.tar.gz"
base_url="https://github.com/kuzmenkodm/rib/releases/download/${version}"

curl -LO "${base_url}/${archive}"
curl -LO "${base_url}/${archive}.sha256"
sha256sum --check "${archive}.sha256"
tar -xzf "${archive}"
mkdir -p "$HOME/.local/bin"
install -m 0755 rib cargo-rib "$HOME/.local/bin/"

Ensure $HOME/.local/bin is in PATH. On Windows, download rib-v0.1.0-x86_64-pc-windows-msvc.zip, verify it against the accompanying .sha256 file, extract rib.exe and cargo-rib.exe, and add their directory to PATH.

From source

git clone https://github.com/kuzmenkodm/rib.git
cd rib
cargo install --path . --locked

All installation methods provide two binaries:

  • rib — the standalone CLI for packaging existing files;
  • cargo-rib — the Cargo subcommand invoked as cargo rib build.

Display the current command-line reference with:

rib build --help
cargo rib build --help

Building from a registry image

The following command adds a prebuilt executable to an Alpine base image and publishes the result directly to a registry:

IMAGE_DIGEST="$(rib build \
  --from alpine:3.22 \
  --platform linux/amd64 \
  --copy ./server:/app/server,mode=0755 \
  --entrypoint /app/server \
  --to registry:registry.example.com/team/server:v1)"

rib fetches the base manifest and configuration but does not perform a full preliminary pull. Inherited layers are reused by digest in the registry. IMAGE_DIGEST receives the digest of the published manifest.

Building from scratch

Use an empty base for a statically linked executable:

rib build \
  --from scratch \
  --platform linux/amd64 \
  --copy ./server:/server,mode=0755,chown=65532:65532 \
  --entrypoint /server \
  --user 65532:65532 \
  --to oci-archive:dist/server.tar@server:v1

scratch is a special marker for an empty base and must be written exactly in that form. scratch:latest is treated as an ordinary image reference that rib will attempt to fetch from a registry.

scratch contains no dynamic loader, system libraries, CA certificates, or shell. Include every runtime dependency in the artifact or add it through another --copy option.

The --copy format

<source>:<destination>[,mode=<octal>][,chown=<uid>[:<gid>]]

Examples:

--copy ./server:/usr/local/bin/server,mode=0755
--copy ./config:/etc/server/,chown=65532:65532
--copy 'target/release/*.so:/usr/local/lib/'

Each --copy creates a separate layer, and layer order follows option order. Destination syntax resembles Dockerfile COPY, but only the subset described in this book is implemented. Symbolic links are unsupported, and a destination for multiple glob matches must end in /. Quote glob patterns so rib, not the shell, expands them.

Output destinations

--to can be supplied more than once:

registry:<image-reference>
oci-archive:<path>[@<tag>]
docker-archive:<path>[@<tag>]

Example:

rib build ... \
  --to registry:registry.example.com/team/server:v1 \
  --to oci-archive:dist/server-oci.tar@server:v1 \
  --to docker-archive:dist/server-docker.tar@server:v1

Destinations are processed sequentially and do not form one transaction.

Authentication

Supply an explicit credential as:

--credential 'registry.example.com=user:password'

Alternatively, rib reads the auths section from one Docker configuration. It selects an explicitly supplied --docker-config, then $DOCKER_CONFIG/config.json, then ~/.docker/config.json. It does not search other files after selecting a configuration. An explicit --credential overrides the selected Docker configuration.

Architecture

This chapter describes the internal components and the overall build pipeline. The following chapters cover layer construction, OCI configuration and manifests, and output formats in more detail.

The standalone rib build CLI and the cargo rib build integration converge on the same pipeline:

rib build   ─────────────┐
                         ├──► ImageBuildSpec ──► BuildRequest
cargo rib build ─► cargo ┘                         │
                                                   ▼
                         ┌────────────────────────────────────┐
                         │ base image + parallel COPY build   │
                         └─────────────────┬──────────────────┘
                                           ▼
                                      ImageBundle
                                           │
                         ┌─────────────────┼─────────────────┐
                         ▼                 ▼                 ▼
                    OCI archive      Docker archive       registry

Once an ImageBuildSpec exists, the request source no longer affects image processing.

Module responsibilities

ModuleResponsibility
cliParses standalone CLI options into a build specification
cargo_integrationCoordinates cli, config, plan, and process for arguments, metadata, build planning, and Cargo execution
app::specDefines settings, merges transport overrides, and validates build requests
app::buildCoordinates the build
app::runtimeInitializes tracing and handles interruption signals
builder::copyParses --copy, expands globs, and resolves image destinations
builder::layerCreates a deterministic tar/gzip layer and its identifiers
imageStores the platform, base image, and layer sources
image::assembleProduces the final configuration, manifest, and ImageBundle
registryWraps oci-client, preserves manifest bytes, and delegates retry policy to registry::retry
app::pushChooses blob reuse, cross-repository mount, or upload
blobLayerStore shares local files, cache lookup, and downloads; concurrent requests for a digest share one download
cacheVerifies cached base layers and publishes complete entries atomically
archiveWrites OCI and Docker archives
authReads Docker configuration and explicit credentials, and canonicalizes registry names
progressProvides terminal, CI-line, and quiet progress modes

The rib and cargo-rib binaries delegate to rib::run() and rib::run_cargo(), keeping lifecycle and error handling shared. These entry points are internal to the binaries and are not a supported, stable library API.

Request normalization

Standalone options become BuildArgs and then ImageBuildSpec. Cargo integration builds the same specification after merging [package.metadata.rib] with CLI values. BuildRequest::try_from validates the main invariants before network or filesystem work starts:

  • --jobs is greater than zero;
  • at least one --to destination is present;
  • --platform matches <os>/<arch>[/<variant>];
  • every --label is a key=value pair;
  • a port without a protocol receives /tcp;
  • --creation-time is epoch, now, or valid RFC 3339;
  • the exact word scratch denotes an empty base; everything else is parsed as an oci_client::Reference.

Downstream components therefore consume one validated request type regardless of the entry point.

Two independent initial branches

Fetching base metadata and creating local layers are independent and run concurrently. The network branch is absent for scratch:

registry base                            scratch
─────────────                            ───────
fetch manifest + config ──┐              create empty config ──┐
                           ├─► assemble                          ├─► assemble
build COPY layers ─────────┘              build COPY layers ────┘

Only the base manifest and configuration are downloaded at this point. Base layer bytes are fetched later for a self-contained archive or when a target registry cannot reuse a layer.

Async and blocking boundaries

Registry access uses the asynchronous oci-client API. Filesystem traversal, tar creation, and gzip compression are CPU- and disk-bound, so every --copy runs in tokio::task::spawn_blocking rather than on Tokio worker threads.

A semaphore of size --jobs limits simultaneous layer builders. Separate semaphores with the same numeric limit constrain later blob downloads and uploads. Results carry their original indices and are reordered before assembly, so completion timing cannot change manifest layer order.

Assembly as the model boundary

Before assembly, the system holds base descriptors/configuration and local Layer values with their digest, diff_id, and temporary storage. The assembler combines them into:

ImageBundle {
    config,
    config_bytes,
    config_digest,
    manifest_bytes,
    manifest_digest,
    layers: Vec<LayerSource>,
}

All registry and archive outputs consume the same bundle and ordered layer list. Every destination in one invocation consequently has the same manifest digest.

Temporary-data lifecycle

A built layer owns an Arc<LayerStorage> for a temporary directory containing layer.tar.gz and, only when a Docker archive is requested, layer.tar. Cloning an image bundle shares these files rather than copying them.

Downloaded base layers are indexed by digest and reused across destinations in one run. Without --cache, temporary data is removed when its last owner is dropped. With --cache, base blobs remain under .rib-cache or --cache-path and are verified by digest before reuse. Built COPY layers are not cached between runs. Verification runs on the blocking pool. Downloads use private staging files and publish atomically after validation, so complete blobs are never truncated. Each reader opens a separate file with its own cursor.

Errors and cancellation

Errors at parsing, layer building, download, assembly, archive writing, and registry publication boundaries receive contextual messages. If a --copy worker fails, a shared cancellation token stops the remaining wrappers; the coordinator waits for them and returns the original contextual error.

Blocking COPY, archive, and decompression writers check cancellation between writes. Ctrl-C and, on Unix, SIGTERM cancel the top-level operation. Temporary directories are owned by RAII values and are cleaned when work is cancelled or fails; an archive is persisted only after its cancellation-safe write finishes.

The oci-client and oci-spec boundary

oci-client is used only for registry transport: authentication, manifest resolution, blob checks, mounts, uploads, and downloads. oci-spec is the canonical in-memory model for platform, descriptors, configuration, and manifest assembly. Adapter code converts registry values once at the boundary, so archive generation and assembly do not depend on registry transport types.

Building COPY layers

Each --copy option creates one deterministic gzip-compressed filesystem layer. This chapter explains path resolution, metadata normalization, hashing, and concurrency.

Syntax

<source>:<destination>[,mode=<octal>][,chown=<uid>[:<gid>]]

source may be a file, directory, or glob. destination is an absolute path inside the image. mode overrides normalized permissions; chown sets numeric UID and GID (GID defaults to UID when omitted).

--copy ./server:/usr/local/bin/server,mode=0755,chown=65532:65532
--copy ./config:/etc/server/
--copy 'target/release/*.so:/usr/local/lib/'

Quote globs so the shell does not expand them before rib receives them. Windows drive paths are supported, for example --copy 'C:\project\app.exe:/app/app.exe'. Artifact paths are treated literally, including names containing glob characters. Names copied into the image must be UTF-8; invalid names produce an error instead of a lossy replacement.

Resolving sources and destinations

A single file copied to a destination without a trailing slash receives that exact path. A file copied to a destination ending in / keeps its basename. Directory contents are rooted below the selected destination. Multiple glob matches require a destination ending in /, preventing ambiguous replacement of several files with one path.

Source paths from standalone CLI options are relative to the current working directory. Cargo metadata paths are resolved relative to that package’s Cargo.toml; CLI additions to cargo rib build remain relative to the process working directory.

Image paths are normalized and rejected if they contain empty, . or .. components. Symbolic links and special filesystem objects are rejected rather than followed. Directory traversal is recursive, but only regular files and directories enter the layer.

Producing a deterministic tar stream

The complete entry list is collected and sorted by destination path before tar writing. Tar metadata is normalized:

  • modification time is 0;
  • UID/GID default to 0, unless chown overrides them;
  • user and group names are empty;
  • explicit mode wins; otherwise directories use 0755, executable files use 0755, and other files use 0644;
  • entry order is stable.

Only the executable bit is inherited from a source file. Host ownership, timestamps, umask, and traversal order do not leak into the image. Directory entries are added as needed so extraction does not depend on implicit parent creation.

Hashing and compression in one pass

The uncompressed tar stream is hashed while being sent to gzip:

source files
    │
    ▼
tar::Builder
    │
    ▼
CancellableWriter
    │
    ▼
SplitWriter
    ├──► HashingWriter ──► optional layer.tar
    │       └── diff_id + uncompressed_size
    │
    └──► GzEncoder
             ▼
          HashingWriter<File> ──► layer.tar.gz
             └── digest + compressed_size

HashingWriter forwards bytes while updating SHA-256 and a size counter. Source data is read once. The uncompressed layer.tar is persisted only for a Docker archive; otherwise diff_id is calculated without retaining that stream. Gzip uses a fixed compression setting.

The result is represented as:

Layer {
    diff_id,
    descriptor,
    uncompressed_size,
    storage: Arc<LayerStorage>,
}

Concurrency preserves order

All copy directives enter a JoinSet, with a semaphore limiting active work to --jobs. CPU- and disk-heavy work runs on the blocking thread pool. Each result retains its input index:

COPY #1 ───────────────► result #1 ─┐
COPY #2 ─────► result #2            ├──► [#1, #2, #3]
COPY #3 ─────────► result #3 ───────┘

The coordinator orders results by directive position, not completion time. If two layers write the same image path, the later directive wins.

Temporary disk usage

At minimum, every new layer needs a compressed temporary blob. Docker archive output additionally needs the uncompressed tar:

registry / OCI archive:
    sum of compressed COPY-layer sizes

Docker archive:
    compressed COPY layers + uncompressed COPY layers

Archive outputs also download base layers. Docker archives temporarily decompress them one at a time. The final archive’s temporary file is created beside its destination and does not consume TMPDIR; layer temporary files do. Plan CI storage for both filesystems. The tempfile crate follows the TMPDIR environment variable on Unix.

Image configuration, manifest, and scratch

Assembly combines the base image, new layers, and runtime metadata into one immutable ImageBundle. It is a CPU-only step over oci-spec values; it does not access the network or filesystem.

Base-image representation

Image {
    source: Option<ImageSource>,
    config: ImageConfiguration,
    layers: Vec<Descriptor>,
}

Some(ImageSource) records a real registry reference and its manifest digest. None represents scratch. An empty base intentionally has no fabricated registry identity that could leak into annotations or publication logic.

Registry base images

For a normal image reference, the registry adapter:

  1. selects credentials;
  2. fetches a manifest or selects a matching manifest from an image index;
  3. fetches the small configuration JSON;
  4. verifies its SHA-256 against the manifest descriptor;
  5. verifies OS, architecture, and optional variant against --platform;
  6. converts layer descriptors from oci-client to oci-spec;
  7. retains descriptors without downloading layer bytes.

Before assembly, rib also verifies that the base layer count equals the number of rootfs.diff_ids. A mismatch indicates an invalid base image.

FROM scratch

The exact word scratch means an entirely empty filesystem. rib creates no registry client, downloads nothing, builds a fresh ImageConfiguration for the selected platform, and starts with empty layers, diff IDs, and history. It adds no base-image name or digest annotations.

scratch:latest and qualified references containing scratch are ordinary registry image names. Once the empty base exists, local layers are added in the same way as for any other image.

For a useful scratch image, supply a self-contained executable, an explicit entrypoint, CA certificates for outbound TLS when needed, and every other runtime file such as configuration, timezone, or user data. Rust applications commonly use a musl target, but toolchain installation and cross-compilation remain the user’s responsibility.

Updating the configuration

The assembler clones the base configuration or starts with an empty one, then:

  1. sets created;
  2. appends every new layer’s diff_id;
  3. appends one non-empty history entry per new layer when history exists;
  4. applies requested runtime metadata;
  5. verifies history/rootfs consistency;
  6. serializes the configuration;
  7. calculates its digest.

New history entries use:

rib copy (<uncompressed-size> bytes uncompressed)

They omit host paths and the full CLI, avoiding publication of internal CI paths or sensitive arguments.

Merging runtime metadata

  • An explicit --entrypoint replaces the base Entrypoint.
  • Replacing it clears inherited Cmd unless --keep-cmd is set or a new --cmd is supplied. Explicit --cmd replaces the inherited value.
  • --label merges into base labels and overwrites matching keys.
  • --port extends base ports without duplicates.
  • --workdir and --user change only when explicitly supplied.
  • Other base metadata, including Env, is preserved.

For scratch, only explicitly supplied runtime fields exist, alongside the builder-generated platform, creation time, rootfs, and history.

History/rootfs invariant

Every history entry without empty_layer: true must correspond to exactly one rootfs.diff_ids entry:

count(history where empty_layer != true) == count(rootfs.diff_ids)

Metadata-only history does not count. A base configuration with no history keeps it absent. A scratch configuration starts with an empty history array, so every new layer receives an entry.

Building the manifest

The assembler creates the configuration descriptor, keeps base layer descriptors in order, appends new descriptors, adds the org.opencontainers.image.created annotation, and records the real base name and digest when applicable. It then serializes and hashes the manifest.

A scratch manifest has no base-image annotations. Each layer retains its origin:

LayerSource::Built(Layer)

LayerSource::FromBase {
    descriptor,
    source: ImageSource,
}

Output code can therefore read a local blob, lazily download a base blob, or avoid a download through cross-repository mount without changing the manifest.

Registries and archive formats

Every output receives the same assembled ImageBundle; writers do not rebuild the configuration or manifest. Registry, OCI archive, and Docker archive outputs from one invocation therefore represent the same image and have the same manifest digest.

No preliminary base-image pull

The initial request fetches only the manifest, configuration, and descriptors. Base layer bytes are downloaded only when:

  • an OCI or Docker archive needs to be self-contained; or
  • a target registry lacks a blob and cannot mount it from the source repository.

For archive output, unique base blobs are downloaded concurrently under the --jobs limit before archive writing begins. For registry output, existing blobs are detected by digest and reused; same-registry sources also attempt a cross-repository mount. scratch has no base-layer download stage.

OCI archive

An OCI archive is a tar file containing an OCI Image Layout:

oci-layout
index.json
blobs/sha256/<manifest-hex>
blobs/sha256/<config-hex>
blobs/sha256/<layer-hex>
...

index.json contains one descriptor for the selected platform. A tag supplied as --to oci-archive:image.tar@app:v1 becomes the descriptor annotation org.opencontainers.image.ref.name, which import tools use as the image tag.

Configuration, manifest, and compressed layers are stored at paths derived from their digests. Duplicate digests are written once.

rib build ... \
  --to oci-archive:dist/image.tar@example/app:v1

Docker archive

A Docker archive is compatible with docker save and docker load:

manifest.json
<config-hex>.json
<diff-id-hex>/layer.tar
...

manifest.json contains optional RepoTags and an ordered layer list. Unlike OCI archives, Docker archives store uncompressed layers and are usually much larger. When such an output is requested, rib retains an uncompressed tar for each new layer and decompresses gzip- or zstd-compressed base layers into temporary files as needed.

rib build ... \
  --to docker-archive:dist/image.tar@example/app:v1

Atomic archive writing

An archive is first written to a temporary file beside its destination. The writer finishes the tar, flushes buffers, calls fsync on the file, and atomically renames it to the target path. If an earlier step fails, an existing destination remains unchanged. Keeping the temporary file beside the target is required because atomic rename is guaranteed only within one filesystem.

Registry publication

For each unique layer, rib uses the first applicable method:

blob exists in the target repository?
    ├── yes ─► reuse it
    └── no
        ├── base layer from the same registry ─► attempt cross-repository mount
        │                                         ├── success
        │                                         └── failure ─┐
        └── built layer or another registry ──────────────────┴─► upload

Cross-repository mount adds a reference to a blob already stored elsewhere in the same registry without transferring its bytes. Built layers are streamed from local temporary storage. A required base layer is downloaded lazily and then streamed to the target.

Layers upload concurrently under the --jobs limit. Configuration is uploaded after layers, and the manifest is published last:

layers ──► config ──► manifest
                       │
                       └── the tag moves at this point

Manifest publication is the commit point. Until then, an existing tag still references its previous manifest; a failure cannot expose a partially uploaded image under the new tag.

Streaming and retries

Uploads use 4 MiB chunks and never load a complete layer into memory. A retry reopens and retransmits the file from the beginning; resumable upload is not implemented.

Timeouts, connection failures, HTTP 408, 425, 429, 500, and 502–599 are retried up to the configured attempt count with exponential backoff and jitter. Authentication and digest errors are not retried. Small configuration and manifest JSON values remain in memory, while layer memory usage stays bounded regardless of image size.

Authentication and transport

Credential resolution for a registry is:

  1. explicit --credential <registry>=<user>:<password>;
  2. auths in the one selected Docker configuration;
  3. anonymous access.

The Docker configuration is selected from --docker-config, then $DOCKER_CONFIG/config.json, then ~/.docker/config.json. No fallback to other files occurs after selection. Docker Hub aliases are canonicalized to registry-1.docker.io. credsStore and credHelpers are not executed.

Source and target registries use separate clients. --from-plain-http and --from-skip-tls affect only the source role; corresponding --to-* options affect every registry destination in that invocation. Use insecure transport only for controlled local or development registries.

Cargo integration

The package installs cargo-rib, which Cargo invokes as:

cargo rib build

The integration converts Cargo metadata and CLI arguments into an ImageBuildSpec, then uses the same image pipeline as rib build.

Operation sequence

cargo rib build:

  1. runs cargo metadata --format-version 1 --no-deps;
  2. selects a workspace package;
  3. reads [package.metadata.rib] from its Cargo.toml;
  4. merges metadata and CLI arguments;
  5. runs cargo build --manifest-path <path> with the configured Cargo args;
  6. verifies that artifact exists and is a regular file;
  7. adds it as the final COPY layer with mode 0755;
  8. assembles and publishes the image through the common pipeline.

Artifact path, platform, and base image are explicit. The integration does not infer a binary target, architecture, or linkage type.

Configuration location and format

Configuration belongs in [package.metadata.rib] for the selected package. Field names use kebab-case, and unknown fields are errors. After metadata and CLI merging, artifact, platform, from, and at least one to destination are required. Any of them may come from either source; to is not restricted to CI and is a normal metadata field.

Artifact and Cargo fields

FieldType and defaultDescription and example
artifactString; required after mergingRegular file produced by Cargo, for example "target/x86_64-unknown-linux-musl/release/taskd". Metadata paths are relative to Cargo.toml.
cargo-argsString array; []Arguments after cargo build --manifest-path <path>, for example ["--release", "--locked", "--target", "x86_64-unknown-linux-musl", "--bin", "taskd"].
destinationString; /app/<artifact name>Absolute artifact path in the image, for example "/usr/local/bin/taskd". It cannot end in /; the artifact is the final layer with mode 0755.
copiesString array; []Extra layers such as ["config/default.toml:/etc/taskd/config.toml", "assets:/opt/taskd/assets/"], inserted before the artifact. Metadata sources are relative to Cargo.toml.

Each copies item uses:

<source>:<destination>[,mode=<octal>][,chown=<uid>[:<gid>]]
copies = [
  "config/default.toml:/etc/taskd/config.toml,mode=0644,chown=65532:65532",
  "assets:/opt/taskd/assets/",
]

Base, platform, and destinations

FieldType and defaultDescription and example
platformString; required after merging<os>/<arch>[/<variant>], such as "linux/amd64" or "linux/arm64/v8". The artifact is not inspected for compatibility.
fromString; required after mergingA base such as "alpine:3.22", a digest-qualified reference, or exact "scratch".
toString array; [], at least one after mergingRegistry, OCI archive, or Docker archive destinations. Multiple values are allowed.

Relative archive paths in metadata are resolved from the Cargo.toml directory. CLI destinations are appended after metadata destinations:

[package.metadata.rib]
to = ["oci-archive:dist/taskd.tar@taskd:local"]
cargo rib build --to registry:registry.example.com/team/taskd:v1

This creates both outputs. There is no CLI replacement mode for to; omit the metadata field when a CI job should publish only to its dynamic destination.

Container runtime configuration

FieldType and defaultDescription and example
entrypointString or string array; [destination]OCI Entrypoint, such as "/taskd --log-format json" or ["/taskd", "--log-format", "json"]. Replacing it clears inherited Cmd unless cmd or keep-cmd = true is set.
cmdString or string array; not explicitly setOCI Cmd, such as ["serve", "--port", "8080"]; replaces inherited Cmd.
labelsString array; []key=value labels merged with base labels; duplicate keys are overwritten.
portsString array; []Ports such as ["8080", "8443/tcp", "8125/udp"]; omitted protocols become /tcp.
workdirString; inheritedProcess working directory, for example "/var/lib/taskd".
userString; inheritedOCI user such as "65532:65532", "1000", or "app"; existence is not checked in rootfs.
keep-cmdBoolean; falseRetains base Cmd when Entrypoint changes; does not override explicit cmd.
creation-timeString; "epoch""epoch", "now", or RFC 3339 such as "2026-08-27T12:00:00Z". Use epoch for reproducibility.

String entrypoint and cmd values use shell quoting rules. Arrays specify argv without further parsing and are preferable when argument boundaries must be exact.

Concurrency and cache

FieldType and defaultDescription and example
jobsPositive integer; available CPUs capped at 4Maximum simultaneous layer builds and blob transfers.
cacheBoolean; falseEnables persistent caching of downloaded base layers, not built layers.
cache-pathString; ".rib-cache" when enabledCache directory such as "/cache/rib". This field alone does not enable caching. Relative paths use the process working directory.

Registry client fields

FieldType and defaultDescription
connect-timeoutPositive integer; 30Connection timeout in seconds.
read-timeoutPositive integer; 60Registry read timeout in seconds.
max-attemptsPositive integer; 3Maximum attempts for each registry operation.
from-plain-httpBoolean; falseHTTP for the source registry; development use only.
from-skip-tlsBoolean; falseDisables source TLS certificate verification; not for production.
to-plain-httpBoolean; falseHTTP for every registry destination; development use only.
to-skip-tlsBoolean; falseDisables certificate verification for every registry destination; not for production.

Credentials, Docker configuration, and progress mode are intentionally absent from metadata. Supply them through --credential, --docker-config, and --progress or the environment; do not put secrets in Cargo.toml.

Metadata and CLI merging

  • CLI scalar values replace metadata values.
  • Explicit boolean flags replace metadata: --cache and --cache=true enable caching, while --cache=false disables it. The same syntax applies to --keep-cmd, --from-plain-http, --from-skip-tls, --to-plain-http, and --to-skip-tls. Omitting the flag retains the metadata value.
  • to, copies, labels, ports, and Cargo arguments are concatenated with metadata values first.
  • The artifact is always the final layer.
  • Artifact and copy sources from metadata are relative to Cargo.toml; CLI sources are relative to the current working directory.

Cargo arguments from the CLI follow -- and are appended after cargo-args:

cargo rib build -- --release --locked --bin taskd

Complete configuration example

This example includes every supported metadata field:

[package]
name = "taskd"
version = "0.1.0"
edition = "2021"
rust-version = "1.94"

[package.metadata.rib]
artifact = "target/x86_64-unknown-linux-musl/release/taskd"
cargo-args = [
  "--release",
  "--locked",
  "--target", "x86_64-unknown-linux-musl",
  "--bin", "taskd",
]
destination = "/taskd"
copies = [
  "config/default.toml:/etc/taskd/config.toml,mode=0644,chown=65532:65532",
  "assets:/opt/taskd/assets/",
]

platform = "linux/amd64"
from = "scratch"
to = [
  "registry:registry.example.com/team/taskd:v1",
  "oci-archive:dist/taskd.tar@taskd:v1",
]

entrypoint = ["/taskd"]
cmd = ["serve", "--port", "8080"]
labels = [
  "org.opencontainers.image.title=taskd",
  "org.opencontainers.image.version=0.1.0",
]
ports = ["8080/tcp"]
workdir = "/"
user = "65532:65532"
keep-cmd = false
creation-time = "epoch"

jobs = 4
cache = true
cache-path = ".rib-cache"

connect-timeout = 30
read-timeout = 60
max-attempts = 3
from-plain-http = false
from-skip-tls = false
to-plain-http = false
to-skip-tls = false

With to configured, no CLI destination is required:

cargo rib build

Credentials remain external:

cargo rib build \
  --credential "registry.example.com=${REGISTRY_USER}:${REGISTRY_PASSWORD}"

For a CI-generated tag, omit metadata to and pass it dynamically:

cargo rib build \
  --credential "$CI_REGISTRY=$CI_REGISTRY_USER:$CI_REGISTRY_PASSWORD" \
  --to "registry:$CI_REGISTRY_IMAGE/taskd:$CI_COMMIT_SHORT_SHA"

This is a configuration choice, not a limitation of Cargo integration.

Configuration without metadata

Every required value can be supplied through CLI options:

cargo rib build \
  --artifact target/x86_64-unknown-linux-musl/release/taskd \
  --platform linux/amd64 \
  --from scratch \
  --to registry:registry.example.com/team/taskd:v1 \
  --destination /taskd \
  --copy config/default.toml:/etc/taskd/config.toml \
  --entrypoint /taskd \
  -- \
  --release --locked --target x86_64-unknown-linux-musl --bin taskd

Workspace package selection

When the current directory is within a Cargo package, that package is chosen. From a virtual workspace root, selection succeeds only with one workspace.default-member or a single package in the workspace. For an ambiguous workspace, run cargo rib build from the required package directory.

Integration limitations

cargo rib build does not detect artifact architecture or linkage, add dynamic loaders or shared libraries, install Rust targets, cross-compile, or discover certificates and other runtime files. With from = "scratch", include all dependencies in the artifact or list them in copies.

Operations

rib is designed primarily for non-interactive CI/CD use while retaining the same interface locally. Production pipelines should pin the builder version, platform, base-image digest, and network settings.

Progress, stderr, and stdout

--progress accepts:

ModeBehavior
autoInteractive UI when stderr is a terminal; line output otherwise
colorForces the interactive UI
plainStable line-oriented CI messages
quietHides progress while retaining the final summary

Progress, warnings, and the summary go to stderr. When stdout is not a terminal, a successful build writes only the manifest digest, without a prefix or trailing newline:

IMAGE_DIGEST="$(rib build \
  --progress plain \
  --from scratch \
  --platform linux/amd64 \
  --copy ./server:/server,mode=0755 \
  --entrypoint /server \
  --to registry:registry.example.com/team/server:v1)"

cosign sign "registry.example.com/team/server@${IMAGE_DIGEST}"

Do not enable shell tracing around commands containing credentials, because the shell may log raw arguments before rib starts.

Concurrency

--jobs limits concurrent COPY builds, base-blob downloads, and target-blob uploads. The default is the available CPU count capped at four. Increasing it may improve network throughput while increasing CPU, disk, and registry load. Reduce it under tight ephemeral-storage or bandwidth limits.

Destinations are processed sequentially in declaration order. Layer operations within one registry destination are concurrent.

Temporary data and base-layer cache

Layer temporary files use the system temporary directory (TMPDIR on Unix). Registry and OCI outputs normally retain only compressed local layers. Docker archive output also retains uncompressed layers. The archive’s own temporary file is created beside its final path.

For large images, provision storage for compressed local layers, downloaded base layers, uncompressed Docker layers, and the temporary final archive.

Downloaded base blobs are not persistent by default. Enable caching with:

rib build ... --cache
rib build ... --cache --cache-path /cache/rib

The default path is ./.rib-cache. Cached blobs are rehashed before reuse. This cache stores downloaded base layers only; it neither stores built layers nor replaces Cargo/npm caches. Multiple rib processes may share the directory: writers use separate staging files and publish atomically after digest and size verification. Incomplete downloads never replace complete entries. Cache verification runs on the blocking pool under --jobs and observes cancellation. A direct push to the same registry usually needs no local cache because registry-side blob reuse avoids downloads.

Network transport

Defaults are a 30-second connect timeout, a 60-second read timeout, three attempts, and HTTPS with certificate verification. Configure these through --connect-timeout, --read-timeout, and --max-attempts.

Source and target insecure options are separate:

  • --from-plain-http, --from-skip-tls;
  • --to-plain-http, --to-skip-tls.

The target options affect all registry destinations in the invocation. Use them only for trusted development infrastructure.

Multiple destinations

rib build \
  --from alpine:3.22 \
  --platform linux/amd64 \
  --copy ./server:/app/server,mode=0755 \
  --entrypoint /app/server \
  --to registry:registry.example.com/team/server:v1 \
  --to oci-archive:dist/server-oci.tar@server:v1 \
  --to docker-archive:dist/server-docker.tar@server:v1

The configuration and manifest are created once, so all outputs have one manifest digest. They do not form a transaction: failure of a later output does not roll back completed registry publications or archives.

Logs and diagnostics

Enable detailed logs with:

RIB_LOG=rib=debug rib build --progress plain ...

RUST_LOG is intentionally not used because cargo rib build launches a user Rust project that may interpret it. Use plain, quiet, or auto in CI; color may emit terminal control sequences.

Termination and partially published data

Ctrl-C and, on Unix, SIGTERM cancel the top-level operation. Copy, archive, and layer-decompression writers check cancellation during writes. A cancelled archive remains temporary and is not published at its target path.

Archives become visible through an atomic rename only after a complete write and file synchronization. Registry manifests are sent after layers and the configuration. Unreferenced blobs uploaded before an error can remain until normal registry garbage collection.

CI/CD, Docker, and Kubernetes

rib runs as an ordinary unprivileged process. A job needs no Docker socket, Docker-in-Docker, privileged container, or access to the node’s container runtime. This applies to shell, Docker, and Kubernetes executors.

A practical build image contains the application’s compiler/runtime, rib or cargo-rib, and pipeline tools such as cosign and the Vault CLI. The runner caches this image through its normal container mechanism; no separate build daemon cache has to be transferred between jobs.

Building a frontend and signing with cosign

This GitLab job assumes that frontend contains built static files, the base image contains execenv and static-web-server, the job image contains rib, Vault, and cosign, and Vault has the corresponding JWT role and Transit key.

default:
  tags:
    - core-os

stages:
  - Build

build_image_rib:
  image: registry.gitlab.com/devdsk/education/rust/rib/rib:v0.1.0
  stage: Build
  id_tokens:
    VAULT_ID_TOKEN:
      aud: https://gitlab.com
  variables:
    VAULT_AUTH_PATH: auth/jwt/login
    VAULT_AUTH_ROLE: cosign
    TRANSIT_SECRET_ENGINE_PATH: cosign
    VAULT_ADDR: https://vault.core-os.ru
    COSIGN_KEY: hashivault://cosign
    HOME: /tmp
  script:
    - |
      IMAGE_DIGEST="$(
        rib build \
          --from "$CI_REGISTRY_IMAGE/frontend-base:1.0" \
          --credential "$CI_REGISTRY=$CI_REGISTRY_USER:$CI_REGISTRY_PASSWORD" \
          --copy "./frontend:/frontend,chown=65532:65532" \
          --entrypoint "/execenv -m error -f /frontend/config.js --exec /static-web-server -p 8787 -d /frontend -g info" \
          --to "registry:$CI_REGISTRY_IMAGE/taskd-frontend:$CI_COMMIT_SHORT_SHA"
      )"
    - |
      VAULT_TOKEN="$(
        vault write --field=token "$VAULT_AUTH_PATH" \
          role="$VAULT_AUTH_ROLE" \
          jwt="$VAULT_ID_TOKEN"
      )"
      export VAULT_TOKEN
    - cosign login "$CI_REGISTRY" -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD"
    - >
      cosign sign --tlog-upload=false
      "${CI_REGISTRY_IMAGE}/taskd-frontend@${IMAGE_DIGEST}"

Progress stays visible on stderr, while IMAGE_DIGEST receives only sha256:...; cosign signs the immutable manifest rather than a mutable tag. There is no preliminary base pull. Because source and target use one GitLab registry, inherited blobs can be reused or mounted without passing through the job filesystem.

Building a Rust project through Cargo integration

Include cargo-rib in an image that already contains the Rust toolchain and the x86_64-unknown-linux-musl target. GitLab caches the builder image, while the Cargo registry and target use the standard CI cache.

default:
  tags:
    - core-os

variables:
  CARGO_HOME: "$CI_PROJECT_DIR/.cargo"

stages:
  - Build

cache:
  key:
    files:
      - Cargo.lock
    prefix: "$CI_COMMIT_REF_SLUG"
  paths:
    - .cargo/registry/index/
    - .cargo/registry/cache/
    - .cargo/git/db/
    - target/

build_image_rib:
  image: registry.gitlab.com/devdsk/education/rust/taskd/rust-builder/rust-rib:alpine3.24
  stage: Build
  script:
    - >
      cargo rib build
      --credential "$CI_REGISTRY=$CI_REGISTRY_USER:$CI_REGISTRY_PASSWORD"
      --to "registry:$CI_REGISTRY_IMAGE/taskd:$CI_COMMIT_SHORT_SHA"

Image parameters live next to the source in Cargo.toml. This example passes --to because its tag is generated by the pipeline; a fixed destination can instead use metadata to.

[package]
name = "taskd"
version = "0.1.0"
edition = "2021"
rust-version = "1.94"

[package.metadata.rib]
artifact = "target/x86_64-unknown-linux-musl/release/taskd"
platform = "linux/amd64"
from = "scratch"

destination = "/taskd"
entrypoint = "/taskd"
workdir = "/"
user = "65532:65532"
ports = ["8080"]
creation-time = "epoch"
jobs = 4
cargo-args = [
  "--release",
  "--locked",
  "--target", "x86_64-unknown-linux-musl",
]

cargo rib build runs Cargo, verifies the artifact, adds it last with mode 0755, and publishes the image. A scratch artifact must be statically linked or accompanied by all runtime dependencies through copies.

Running in a Kubernetes executor

With GitLab Runner’s Kubernetes executor, these jobs require no custom Kubernetes manifest. The runner creates an ordinary pod from the selected job image. Configure only normal resource requests and limits, network access to the registries and secret services, and sufficient emptyDir/ephemeral storage for Cargo outputs, temporary layers, and archives. No host paths, Docker socket, or privileged security context are required.

Reproducibility and security

What a reproducible result means

With identical inputs and the same rib and dependency versions, reproducibility means byte-for-byte identical layers, configuration, manifest, and digest—not merely equivalent filesystem contents.

rib removes common tar/gzip variability:

  • tar entries are sorted;
  • every entry has mtime = 0;
  • default UID/GID is 0, and user/group names are empty;
  • permissions follow fixed normalization rules;
  • gzip uses a fixed compression setting;
  • image creation time defaults to the Unix epoch;
  • concurrently built layers are restored to input order.

--creation-time now intentionally makes configuration and manifest depend on wall-clock time. For reproducibility, use epoch or a fixed RFC 3339 value such as the commit time.

Factors that affect output

Result bytes depend on source contents and executable bits, copy list and order, explicit mode/ownership, platform, base configuration and descriptors, runtime metadata, and the exact rib and serialization/compression dependency versions.

Base tags are mutable. Pin a digest for strict repeatability:

rib build \
  --from alpine@sha256:<manifest-digest> \
  --platform linux/amd64 \
  ...

Treat the builder version as part of provenance and pin it in CI.

Data integrity

Downloaded base configuration bytes are rehashed and checked against the manifest descriptor. Assembly verifies layer/diff-ID counts and history consistency. The summary goes to stderr; redirected stdout receives only the manifest digest, which can be stored as an immutable deployment reference.

rib does not sign or create provenance. Pass the digest to a dedicated tool:

IMAGE_DIGEST="$(rib build ... --to registry:registry.example.com/team/app:v1)"
cosign sign "registry.example.com/team/app@${IMAGE_DIGEST}"

Credentials

  • Prefer a read-only Docker configuration or an external secret store over a literal password.
  • Never store credentials in Cargo.toml; metadata deliberately excludes them.
  • Do not use set -x around --credential.
  • Scope tokens to the required repositories and pull/push permissions.
  • Where the threat model requires it, use separate source and target registry accounts. Credentials are selected by registry host, so separate identities for two repositories on the same host are not supported within one run.

TLS

HTTPS with certificate verification is the default. Plain HTTP removes encryption; --*-skip-tls keeps HTTPS but disables server identity validation. Source and destination roles are configured separately, but an insecure target option affects every target registry in that invocation. Do not combine a development target requiring --to-skip-tls with a production target in the same command.

--copy as a trust boundary

rib reads every explicitly selected file and every glob match. There is no .dockerignore equivalent. Broad source directories can accidentally include .env, private keys, credentials, source code, .git, or logs. Prefer narrow paths and inspect resulting images or archives in CI.

Symbolic-link sources and special files are rejected. Destination paths with empty, . or .. components are also rejected, preventing unexpected filesystem traversal.

scratch and runtime security

scratch minimizes included files but does not automatically secure an application. Keep static dependencies updated, add CA certificates when needed, set a non-root user, exclude secrets, provide application-level logs, metrics and health checks, and scan the executable itself.

Minimal images contain no shell for interactive diagnosis. In Kubernetes, plan for ephemeral debug containers rather than relying on kubectl exec into the application image.

Publication safety

An archive replaces its target only after a complete write, file synchronization, and atomic rename. A registry manifest is published only after all layers and configuration are available. These mechanisms prevent partial results from becoming visible, but multiple --to destinations are still not one transaction and cannot roll one another back.

Limitations

Image construction

  • Only file addition through COPY and runtime metadata changes are supported; there is no RUN or Dockerfile parser.
  • Package installation and whiteout layers for removing base files are absent.
  • Symbolic links and special source files are rejected.
  • File names copied into the image must be UTF-8; invalid names are rejected instead of being silently replaced.
  • One invocation creates one platform-specific manifest. Build a multi-platform index with another tool or pipeline stage.
  • scratch contains no libc, CA certificates, shell, or runtime files.

Caching

  • Without --cache, downloaded base blobs are removed after the process exits.
  • The cache stores only downloaded base layers, not built COPY layers.
  • Registry-side blob checks and cross-repository mounts normally make a local cache unnecessary for repeated pushes to the same registry.

Cargo integration

  • Artifact, platform, and base image are explicit.
  • Cross-compilation, target installation, and binary-target selection are not automatic.
  • Artifact architecture and linkage are not inspected.
  • In an ambiguous workspace, run the command from the required package.

Registries and publication

  • Multiple destinations are sequential and non-transactional.
  • A failure in a later destination does not roll back earlier results.
  • Blob retries restart from the beginning; resumable upload is absent.
  • Docker credential helpers are not executed; only explicit credentials and the auths section are supported.
  • Signing, SBOM, and provenance are external; stdout exposes the manifest digest for tools such as cosign.

Possible future work

  • caching built layers;
  • multi-platform index generation;
  • registry-native referrers for SBOM and provenance;
  • resumable uploads;
  • external credential providers and cloud workload identity;
  • coordination across multiple publication destinations.