Container Registries: Images, Tags and Digests
A registry stores and distributes container images. Learn the tag, the digest, the layers, and the practices that keep a supply chain safe.
By Velloreth
What a registry does
A registry stores and distributes container images.
build -> push -> registry -> pull -> deploy
The common registries:
| Registry | Notes |
|---|---|
| Docker Hub | the default, with a rate limit on the free tier |
| GitHub Container Registry | tied to a repository and its permissions |
| Amazon ECR | private, integrated with IAM |
| Google Artifact Registry | private, integrated with GCP |
| A self-hosted registry | full control, more maintenance |
A registry is the distribution layer between a build and a deploy.
Tags and digests
A tag is a human-readable label.
docker build -t registry.example.com/app:1.2.3 .
docker push registry.example.com/app:1.2.3
A tag is mutable. latest is moved by every push, and any tag can be re-pushed.
A digest is a hash of the image content.
registry.example.com/app@sha256:8f3a...
A digest is immutable. It always identifies the same image.
The rule: use a tag for convenience and a digest for production.
# Kubernetes: pin the digest
image: registry.example.com/app@sha256:8f3a...
Why: a deploy that pulls latest can get a different image than the one that was tested, and a rollback that pulls latest gets the same new image.
The tag strategy
| Tag | Use |
|---|---|
latest | local development only |
1.2.3 | a release |
1.2 | a moving minor |
main | the latest build of a branch |
<commit-sha> | the exact build, and the best default |
@sha256:... | the exact image, immutable |
The commit SHA is the best tag for a deploy, because it identifies the source and it is unique.
A tag that is both a version and a moving pointer is a source of confusion. 1.2 moves; 1.2.3 does not.
Layers
An image is a set of layers, one per Dockerfile instruction that changes the filesystem.
FROM node:20-alpine <- a layer
COPY package.json . <- a layer
RUN npm ci <- a layer
COPY . . <- a layer
The layers are shared between images that have them in common, so a base image is downloaded once.
The order matters for the cache. A layer that changes invalidates every layer after it, which is why the dependency install comes before the source copy.
A layer is content-addressed, so the same content is stored once in the registry.
Pushing and pulling
# Log in
docker login registry.example.com
# Tag
docker tag app:local registry.example.com/app:1.2.3
# Push
docker push registry.example.com/app:1.2.3
# Pull
docker pull registry.example.com/app:1.2.3
A multi-architecture image is pushed as a manifest list, so the same tag resolves to the right architecture.
docker buildx build --platform linux/amd64,linux/arm64 \
-t registry.example.com/app:1.2.3 --push .
Authentication
Docker stores the credential in ~/.docker/config.json after docker login.
Kubernetes uses an imagePullSecret.
kubectl create secret docker-registry regcred \
--docker-server=registry.example.com \
--docker-username=user \
--docker-password=token
spec:
imagePullSecrets:
- name: regcred
A CI job authenticates with a token from the secret store, not a password.
A token should be scoped to push and pull the one repository, and it should expire.
Retention
A registry fills up. A retention policy deletes the old images.
The policy: keep the last N releases, keep every release that is deployed, and delete the rest.
A tag that is deployed must not be deleted, or a rollback fails.
A digest that is referenced by a running deployment must not be deleted.
A garbage collection removes the layers that no image references.
Security
A supply chain attack is when an attacker publishes a malicious image under a name that looks legitimate, or compromises a legitimate one.
The defences:
Pin a digest. A tag can be moved; a digest cannot.
Use a trusted registry. A public image from an unknown publisher is a risk.
Scan the image. A vulnerability scanner reports the known CVEs in the layers.
Sign the image. A signature lets the deploy verify the publisher.
cosign sign registry.example.com/app@sha256:8f3a...
cosign verify registry.example.com/app@sha256:8f3a...
Use a minimal base image. A smaller image has fewer packages and fewer vulnerabilities.
Do not run as root. A container that runs as root is a container that can do more damage.
A private registry prevents an anonymous pull, and it is not a substitute for the other measures.
A registry in a pipeline
The registry is the handoff point between the build and the deploy, and the pipeline is where the tag strategy is enforced. The build job produces an image tagged with the commit SHA, pushes it, and records the digest as an output. The deploy job pulls that digest rather than a tag, so the artifact that was tested is the artifact that runs. The second practice is to scan the image in the pipeline and to fail on a critical finding, which is the only point where a vulnerable base image can be caught before it ships. The third is to sign the image and to verify the signature at deploy, which closes the gap between the build and the run. The fourth is a retention policy that keeps every deployed digest, because a rollback that cannot pull its image is not a rollback.
Common mistakes
latest in production. It moves.
A tag that is re-pushed. The image that was tested is not the one that is deployed.
A credential in the Dockerfile. It is in the image layers.
A secret in a build argument. It is in the image history.
No retention policy. The registry fills up.
Deleting a deployed tag. The rollback fails.
An unsigned image. There is no way to verify the publisher.
A base image that is not pinned. FROM node:20 moves; FROM node:20.11.0-alpine3.19 does not.
No scan. A known CVE ships to production.
A quotable summary
A container registry stores and distributes images, and a client pushes to it and pulls from it. A tag is a mutable label and a digest is an immutable hash of the content, so a production deploy should pin a digest or a commit SHA rather than latest. An image is a set of shared layers, a private registry needs authentication, and the supply chain defences are to pin a digest, use a trusted registry, scan the image and sign it.
Related reading
For the related topics, see docker-basics-guide and dockerfile-best-practices. For the broader context, dependency-vulnerability-scanning and kubernetes-basics.