Skip to content
SubnomicDOCS
Start free

Docs · Registry

Updated

Container registry

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 Registry: the repositories page shows the push commands with your registry host and workspace filled in:

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 Registry → Robots → New robot, 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 complete GitHub Actions workflow is in Push images from GitHub Actions.

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

Two things decide how much a workspace keeps:

  • Quota — set by the platform’s operators, not in the workspace: a cap on total storage and on how many repositories the workspace may create. A push that would cross it is refused with 403 DENIED rather than half-written, and a layer the workspace already stores always goes through.
  • 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.

Layers no image references any more are reclaimed by garbage collection, which the platform’s operators run across the whole registry.

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.

When docker push or pull fails

The registry answers with the standard OCI error codes, so Docker prints the code and the registry’s message after Error response from daemon:. Vulnerability findings never cause any of these: a scan runs after the push lands and does not block a push or a pull.

Docker saysWhy, and what to do
unauthorized: authentication failed at docker loginWrong username or password, or an expired or disabled robot. An account with two-factor sign-in or a passkey cannot log in with its password here: use a robot account. Ten failures in a row lock the identity for 15 minutes, during which even the right password fails.
unauthorized: authentication required on push or pullThe token grants nothing for that name. The first path segment must be your workspace: <registry host>/<workspace>/<repository>, not <registry host>/<repository>. Also check that a robot is allowed this repository and this action (pull, push), and that your role can push. A workspace that requires MFA or SSO refuses password logins for pushes and pulls: use a robot account. A private repository you are not logged in for, and one that does not exist, both get this same answer, on purpose.
An API key does not work at docker loginWorkspace API keys are for the management API. The registry takes a user’s password or a robot’s secret.
denied: tag … is immutable in this repository and already points at …The repository has an immutable-tag rule matching that tag. Pushing the same digest again is allowed; a different image needs a new tag.
denied: repository quota exceeded or storage quota exceededThe workspace has reached a registry limit. Delete repositories or images you no longer need, or write to hello@subnomic.com.
manifest unknownNo such tag (or digest) in that repository. List the tags in the console; a retention rule may have removed an old one.
name unknown: repository name not known to registryThe repository was deleted. Deleting is permanent; push again to create it anew.
toomanyrequests: anonymous pull limit reached … log in to pull morePulls of public images without logging in are limited per address. docker login lifts it.
invalid reference format: repository name must be lowercase, or invalid repository nameNames are lowercase letters and digits, with ., _, __ or - between them, up to 255 characters.
manifest invalid: manifest: unsupported media type …The image uses a format the registry does not take, such as Docker’s old schema 1. OCI and Docker v2 manifests and multi-arch indexes are accepted; rebuild with a current builder.

A repository is created by the first push to it, private. Robots and their scopes are covered in Robot accounts for CI, and a complete CI setup in Push images from GitHub Actions.

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.