Container registry — Subnomic Docs

A private registry for your container images, inside your workspace. Push with the tools you already use — docker, podman, oras, crane — and browse repositories, tags and layers from the UI. Images are private to your workspace: another workspace cannot pull them even if it learns a digest.

Push your first image

Every repository you own lives under your workspace's namespace, so the full name is <workspace>/<repository>. Open Infrastructure → Container registry → Repositories and use Push commands — the page fills in your registry host and username for you:

docker login <registry host> -u <your username>
docker tag my-app:latest <registry host>/<workspace>/my-app:latest
docker push <registry host>/<workspace>/my-app:latest

The repository appears as soon as the first push lands. You can also create an empty one first with Create repository — useful when you want the description and visibility set before CI pushes to it.

Docker Desktop runs the daemon inside a VM, so a registry reachable at localhost on your machine may not be reachable from the daemon. If a local push hangs or 401s, use a host-side client such as crane copy instead, or ask your operators for the published address.

Robot accounts for CI

Do not put a person's login in a pipeline. Under Container registry → Robots, create a robot with just the actions it needs — pull for a deployer, pull + push for a build job. The secret is shown once, as a ready-to-paste docker login line; store it in your CI secret manager.

A robot only ever reaches your own workspace's namespace. You can disable one without deleting it (handy while you rotate), rotate its secret in place, or delete it outright — any of the three stops the robot getting new tokens, and a token it already holds expires within minutes.

Tags, manifests and multi-arch

Open a repository to see its tags with architecture, OS, size, who pushed and when. Click a tag to inspect the manifest: the config, the ordered layer list and, for a multi-arch image, each per-platform child. The docker pull command for the exact digest is one click away — pin by digest rather than tag when you want a deployment to be reproducible.

Layers are stored once and shared across every image that uses them, so pushing ten tags of the same app costs far less than ten times one image. The size shown for a repository counts each distinct layer once.

Keeping storage under control

Under Registry maintenance:

Quota — if your operators set one, a cap on total storage and on how many repositories the workspace may create. A push that would cross the limit is refused rather than half-written.
Retention — per repository, keep the last N tags and/or anything pushed within N days, optionally limited to tags matching a pattern. Setting both to zero means "keep everything", so a half-filled form can never quietly delete your images.
Garbage collection — reclaims layers no image references any more. It runs every hour on its own.

Deleting a tag or a repository is not reversible. Garbage collection then removes the layers nothing else uses, so the bytes really are gone — export anything you may need first.

Import and export

Copy an image in from another registry (Docker Hub, GHCR, ECR…) or push one back out, without pulling it to your laptop first. Give the upstream reference and, for a private source, its credentials; the transfer runs in the background and reports progress, and you can cancel or retry a job from the same page.

Who can do what

Registry actions are ordinary workspace permissions, editable per role under Roles. Browsing, pushing, deleting, managing robots, changing quota and retention, running garbage collection and viewing statistics are each separate — so a deploy role can pull without being able to delete, and a viewer can see what exists without touching it.

For vulnerability scanning, SBOMs and image signing, see Image security.