mise-en-place

Appearance

mise oci push ​

[experimental] Build an OCI image and push it to a registry

Pushes with mise's built-in registry client — no skopeo/crane/docker required. If --image-dir is not passed, builds fresh from the current mise.toml first. Only blobs the registry doesn't already have are uploaded, so repeat pushes of mostly-unchanged toolsets are cheap.

Tool layers whose tool, version, mount point, and file owner match the previously pushed image (or --cache-from) are reused without being rebuilt — those tools don't even need to be installed locally. Pass --no-cache to force a full local rebuild.

Credentials are read from the same places docker and podman use: $REGISTRY_AUTH_FILE, $XDG_RUNTIME_DIR/containers/auth.json, ~/.config/containers/auth.json, and ~/.docker/config.json (including credential helpers) — so docker login / podman login is all the setup needed.

Requires mise settings experimental=true (or MISE_EXPERIMENTAL=1).

Arguments ​

  • <REF> — Destination registry reference (e.g. ghcr.io/me/devenv:latest)

Flags ​

  • --cache-from <REF> — Reuse unchanged tool layers from this image instead of the destination ref

    Must live in the same repository as the destination. Useful when each push gets a unique tag (e.g. per-commit tags in CI): --cache-from ghcr.io/me/dev:latest ghcr.io/me/dev:$SHA.

  • --from <FROM> — Base image for the build (ignored with --image-dir)

  • --image-dir <IMAGE_DIR> — Push an already-built OCI image layout (skip the build step)

  • --include-global — Also include tools from the global / system config (default: project-only)

    See mise oci build --help for details.

  • --mount-point <MOUNT_POINT> — Override in-image mount point (ignored with --image-dir)

  • --no-cache — Don't reuse tool layers from the previously pushed image

  • --no-mise — Don't embed the mise binary (ignored with --image-dir)

  • --owner <UID[:GID]> — UID[:GID] to assign to every tar entry when building (conflicts with --image-dir)

    Overrides [oci].user_id / [oci].group_id. Defaults to 0:0. If GID is omitted, it defaults to UID. This affects file ownership only; [oci].user controls the image USER directive.

  • --update-index — Maintain the tag as a multi-arch image index

    Pushes this build's manifest by digest and points the tag at an OCI image index containing one entry per platform, preserving entries other architectures pushed. Run mise oci push --update-index from one runner per platform to assemble a multi-arch tag.

  • -h --help — Print help

Examples ​

Build and push to GHCR:

mise oci push ghcr.io/me/devenv:latest

Push an image built earlier:

mise oci build -o ./img
mise oci push --image-dir ./img ghcr.io/me/devenv:v1

Auth:

Credentials are resolved the same way docker/podman resolve them:
$REGISTRY_AUTH_FILE, $XDG_RUNTIME_DIR/containers/auth.json,
~/.config/containers/auth.json, then ~/.docker/config.json
(inline auths and credential helpers). Log in with either:
$ docker login ghcr.io
$ podman login ghcr.io
MIT LicenseCopyright © 2026jdx.dev