Registries, tags and image distribution

How an image name is assembled, why digests are the only immutable reference, and pushing to Docker Hub, GHCR or a private registry.

Anatomy of an image name

registry.example.com/team/api:1.4.2-alpine
└────────┬──────────┘ └─┬─┘ └┬┘ └────┬─────┘
     registry host     namespace repo    tag

nginx                       -> docker.io/library/nginx:latest
ghcr.io/acme/api:sha-9f3c1  -> tag carries the commit
app@sha256:8f1c...          -> digest: immutable, exact bytes

• Omit the registry host and Docker Hub is assumed; omit the namespace and library is assumed for official images.
• A tag is a mutable pointer that can be moved to a completely different image at any time. A digest always resolves to the same content.
• latest is only the default tag — it is not the newest build, and pulling it twice can give you two different images.
• Repository names must be lowercase; a mixed-case name fails at push time, which is the classic first push error.

docker tag app:local registry.example.com/team/app:1.4.2
docker tag app:local registry.example.com/team/app:1
docker push registry.example.com/team/app:1.4.2
docker push registry.example.com/team/app:1

# pin the exact bytes you tested
docker inspect --format='{{index .RepoDigests 0}}' registry.example.com/team/app:1.4.2
docker pull registry.example.com/team/app@sha256:8f1c9a4e...

Logging in and pushing

# never let the password reach the shell history or process list
echo "$REGISTRY_TOKEN" | docker login registry.example.com -u ci --password-stdin
docker logout registry.example.com

# GHCR push from a workstation
echo "$GHCR_PAT" | docker login ghcr.io -u "$GITHUB_USER" --password-stdin
docker tag app:local ghcr.io/acme/app:1.4.2
docker push ghcr.io/acme/app:1.4.2

# a local registry for the lab, and its catalogue
docker run -d -p 5000:5000 --name registry -v registry:/var/lib/registry registry:2
docker tag app:local localhost:5000/app:test
docker push localhost:5000/app:test
curl -s localhost:5000/v2/_catalog

• Credentials land in ~/.docker/config.json, base64-encoded rather than encrypted. Configure a credential helper (docker-credential-desktop, pass, secretservice) for anything long-lived.
• In CI, log in with a short-lived token scoped to push only that repository, and log out in a cleanup step.
• A registry on plain HTTP must be listed in insecure-registries in daemon.json; doing the same thing in production gives away credentials on the wire.
• Push the tag and the digest you tested. Rebuilding at deploy time can produce a different image from the one that passed CI.

Manifests, digests and multi-architecture tags

docker buildx imagetools inspect registry.example.com/team/app:1.4.2
docker manifest inspect alpine:3.20 | head -40

# what the tag actually points at, per platform
docker buildx imagetools inspect --raw nginx:1.27-alpine | jq '.["mediaType"]'

# force the platform you want instead of the emulated default
docker pull --platform linux/arm64 alpine:3.20
docker run --rm --platform linux/amd64 alpine:3.20 uname -m

• One tag may point to a manifest list — an index of per-platform manifests — so docker pull picks the image matching your architecture automatically.
• A digest identifies one platform-specific manifest, not the whole list, so --platform and @sha256: must agree.
• Copy an image between registries without pulling it locally with docker buildx imagetools create --tag.
• Removing a tag from a registry does not always remove the layers immediately; retention policies and garbage collection are registry features, not Docker ones.

FAQ

Related

BuildKit, cache and multi-platform images Docker in CI and publishing images

Last refreshed 2026-09-18.