Proposal: mise oci build --copy HOST_PATH:IMAGE_PATH for baking arbitrary host paths as reproducible layers

[karteekiitg]

What's missing

mise oci build can bake tools, apt packages, and dotfiles into an image, but there is no way to place an arbitrary host file or directory at a chosen path in the image. Today the only escape hatch is to drop out to a Dockerfile wrapper (COPY) after the build, which leaves mise's reproducible layer machinery behind and reintroduces the non determinism that mise's OCI layers are designed to avoid.

Proposal

Add a repeatable flag, and a matching [[oci.copy]] config table:

mise oci build --copy HOST_PATH:IMAGE_PATH [--copy HOST_PATH2:IMAGE_PATH2 ...]

[[oci.copy]]
host  = "HOST_PATH"
image = "IMAGE_PATH"

[[oci.copy]]
host  = "HOST_PATH2"
image = "IMAGE_PATH2"

host is a path on the build host (file or directory). image is an absolute path in the resulting image.

Behavior

1. stat the host path locally to decide file vs directory. Its content lands at the image path. Create parent directories in the image if they do not already exist.
2. Emit through the existing build_layer_from_dir (directory) or the single file path. This is the same symlink preserving emitter already used for tool layers, so it is deterministic out of the box: mtimes zeroed, owner normalized via --owner, executable bits preserved (0o755 / 0o644).
3. Each copy entry produces one independent layer (both the flag and the table may be repeated), appended after the tool layers. Layers are content addressed by their digest, so one layer per payload keeps the cache economics of one layer per tool: changing one payload invalidates only its own layer and leaves every tool layer, the base, and the image config reused.
4. Annotate each layer (for example dev.mise.copy plus the target path) so it is inspectable via skopeo inspect.

Why this fits the existing design

The layer emitter already exists and is hardened for reproducibility; this only exposes it for host paths that are not part of a tool install. The flag surface matches the current oci build flags (--from, --output, --owner, --tag, --mount-point, --no-mise). The [[oci.copy]] table mirrors the flag and is consistent with [oci] already carrying array fields (entrypoint, cmd).

Use cases

The intent here is a general, future looking primitive, not a Rust fix. mise oci build positions itself as a reproducible alternative to a Dockerfile, yet it has no equivalent of the single most common Dockerfile instruction, COPY. A generic copy serves a broad set of needs, for example:

• prebuilt binaries or artifacts produced earlier in a pipeline
• CA bundles, license or compliance files, and other fixed assets
• vendored dependencies or caches you want baked in
• entrypoint or helper scripts, and static assets
• out of tree tool payloads that mise installs but does not keep under a single install dir

That last category is where I hit the gap concretely. With Rust, the toolchain lives under RUSTUP_HOME (toolchains/<tc>/), outside installs/rust/<version>/, so a mise oci build image has the cargo proxy shims but not the toolchain behind them. A generic copy lets the caller bake such payloads into the image at known paths and point the relevant env at them, with no tool specific logic in mise. Solving it generically keeps that special case out of mise core and covers the other use cases at the same time.

Open questions for direction before I open a PR

1. Key names for the table: host / image, or something more explicit like host_path / image_path?
2. Should config values support {{ }} or env interpolation, for dynamic host paths (versioned payloads produced in CI)?
3. Preferred annotation key.

Closing

@jdx this one is more involved and more debatable than my last change, and it defines a new seam for oci at the layer emitter level, so I would rather not assume the shape. I would appreciate your comments or suggestions. If it sounds reasonable as proposed, I am happy to raise the PR. Even just a steer on flag plus [[oci.copy]] vs a different surface would be enough for me to proceed. Does that work?

[jdx]

Thanks for the detailed proposal. I implemented this in #10952 with the --copy HOST_PATH:IMAGE_PATH flag and repeated [[oci.copy]] tables using host / image. Each payload is emitted as an independent reproducible layer after the tool layers and annotated with dev.mise.copy=<image path>. Files land at the exact target path, while directory contents land beneath the target. The implementation also validates absolute image paths, creates parent directories, preserves symlinks and executable modes, and applies the existing OCI owner settings.\n\nI kept the initial surface deliberately literal—there is no additional {{ }} or environment interpolation specific to these fields in this PR.\n\nThis comment was generated by an AI coding assistant.

[karteekiitg]

wow that was quick. this looks great, thanks. should be useful for a lot of cases - i'll test it out and let you know, in case i find anything

also, maybe worth commenting on action rust cache issue - that this honestly a better path than action - maybe once oci comes out of beta.