Push and pull container images

Select the exact namespace/repository once. rvs supplies temporary authentication for that OCI-enabled repository.

Build and push with Docker

rvs art select platform/runtime-images
rvs docker build -t acme/api:1.0.0 .
rvs docker push acme/api:1.0.0

Before pushing, rvs shows the destination and image and asks for confirmation. Use --rvs-yes only in a guarded automation job.

Docker may upload several missing layers concurrently. Ravenstash keeps each blob upload durable and resumable; a manifest becomes pullable only after every referenced blob is present and valid.

Push a multi-platform image

Buildx output tags still need the full image reference:

rvs art select platform/runtime-images
rvs docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --tag oci.rvsta.sh/platform/runtime-images/acme/api:1.0.0 \
  --push .

Pull by tag

rvs art select platform/runtime-images
rvs docker pull acme/api:1.0.0

Pull keeps the full image name printed by rvs; it does not create a local acme/api:1.0.0 alias. Use the printed reference when running the image. For deployment pinning, copy the manifest digest from Docker or the Ravenstash content view and use rvs docker pull acme/api@sha256:....

Names and local tags

Push, pull, and tag accept nested image paths such as team/backend/api. An omitted tag means latest. Push automatically creates the full destination tag from your local image, preserving the original tag. To give an existing local image a different destination name:

rvs art select platform/runtime-images
rvs docker tag local-api:dev acme/api:next

If the full local destination tag already points to another image, rvs stops. To replace it intentionally, use plain docker tag <source> <full-destination>. This can be necessary after rebuilding latest. A full tag created by push remains locally even if uploading fails. push --all-tags requires a full image reference; pull --all-tags acme/api supports shorthand.

Explicit registry hosts are never redirected. Docker treats a first path component containing a dot or colon, localhost, or uppercase letters as a registry host. Use the full internal reference for paths such as team.v2/api. A missing private image never falls back to Docker Hub; use plain docker pull nginx:alpine for a public pull.

Build with private and public images

Dockerfile references keep their normal meaning. Private bases need a full reference; public bases use their own registries:

FROM oci.rvsta.sh/platform/runtime-images/acme/build-tools:1.0.0 AS build
WORKDIR /src
COPY . .
RUN ./build.sh

FROM docker.io/library/nginx:alpine
COPY --from=build /src/dist /usr/share/nginx/html

rvs art select platform/runtime-images
rvs docker build -t acme/site:1.0.0 .
rvs docker push acme/site:1.0.0

The build receives temporary access to the selected private repository and preserves your existing credentials for other registries. All Ravenstash base images must belong to that selected repository. Build output tags, Dockerfile references, and ORAS commands are not expanded by Docker shorthand.

Use ORAS

ORAS can copy OCI content and discover subject-linked attachments. The manifest identifies whether content is a container image or a Helm chart:

rvs art select platform/runtime-images
rvs oras discover \
  oci.rvsta.sh/platform/runtime-images/acme/api:1.0.0

The same temporary credential behavior applies to rvs oras. Secrets are not placed in command arguments or written into your persistent Docker configuration.

ORAS and Helm send each blob in a single upload request through oci.rvsta.sh, which accepts at most 100 MiB per request. A larger blob fails with HTTP 413 (occasionally 502). Push images with larger layers with Docker, Podman, Skopeo, or Crane, which upload layer bytes directly to Ravenstash’s upload origin and have no such limit. Downloads are not affected.

Interrupted uploads

An interrupted layer upload does not publish a partial image. A compatible client can resume the upload while it remains valid or start a replacement upload.

Other compatible clients

The registry protocol is compatible with Docker, ORAS, Podman, nerdctl, Skopeo, and Crane. rvs docker and rvs oras provide credential injection today; other clients can use a short-lived exact-target credential obtained through Ravenstash tooling.

Use Docker or ORAS directly

Mint a short-lived OCI token for the exact repository. Use --access read for pull-only work or --access publish for pushes:

RVS_NATIVE_TOKEN=$(rvs art token mint \
  --target platform/runtime-images \
  --format oci \
  --access publish)
export RVS_NATIVE_TOKEN

Print the registry host, generate a complete client recipe, or print one full image reference:

rvs art endpoint --target platform/runtime-images --format oci
rvs art native config docker --target platform/runtime-images --access publish
rvs art native config oras --target platform/runtime-images --access publish
rvs art reference acme/api:1.0.0 \
  --target platform/runtime-images --format oci

endpoint only prints the registry host. reference qualifies one image path. native config prints login and package commands without changing client state, minting a token, or running the client.

Native OCI clients save login credentials. Use a temporary configuration to avoid modifying a shared Docker or ORAS login store:

RVS_OCI_CONFIG=$(mktemp -d)
chmod 700 "$RVS_OCI_CONFIG"

Docker

printf %s "$RVS_NATIVE_TOKEN" | \
  docker --config "$RVS_OCI_CONFIG" login oci.rvsta.sh \
  --username rvs --password-stdin

docker --config "$RVS_OCI_CONFIG" pull \
  oci.rvsta.sh/platform/runtime-images/acme/api:1.0.0

docker --config "$RVS_OCI_CONFIG" tag LOCAL_IMAGE \
  oci.rvsta.sh/platform/runtime-images/acme/api:1.0.0
docker --config "$RVS_OCI_CONFIG" push \
  oci.rvsta.sh/platform/runtime-images/acme/api:1.0.0

ORAS

printf %s "$RVS_NATIVE_TOKEN" | \
  oras login --registry-config "$RVS_OCI_CONFIG/oras.json" \
  oci.rvsta.sh --username rvs --password-stdin

oras manifest fetch --registry-config "$RVS_OCI_CONFIG/oras.json" \
  oci.rvsta.sh/platform/runtime-images/acme/api:1.0.0

Delete the temporary credentials after finishing:

rm -r -- "$RVS_OCI_CONFIG"
unset RVS_OCI_CONFIG RVS_NATIVE_TOKEN

See Use tokens with package tools for expiry, access, and rotation details.