Registries: Docker Hub, GHCR, ECR and tags you can trust

What's in a name

An image lives in your local Docker until you push it to a registry, a server that stores images so other machines can pull them. The full name says where:

ghcr.io / acme/price-api : 1.4.0  @sha256:034074b2…
registry   repository     tag      digest

Leave out the registry and Docker assumes Docker Hub: nginx:1.30-alpine is really docker.io/library/nginx:1.30-alpine. To push, you tag the image with the registry's name, then push. Try it with a registry running on your own machine:

$ docker run -d --name registry -p 127.0.0.1:5000:5000 registry:3
$ docker tag price-api:multi localhost:5000/price-api:1.0.0
$ docker push localhost:5000/price-api:1.0.0
96ed2737ae31: Pushed
a5789fc40e82: Pushed
b8b68e3af840: Pushed
1.0.0: digest: sha256:034074b20fb92e756118038e8c32abeb0c269da12b78451263de0b83cdef6ccd size: 856
$ docker tag price-api:multi localhost:5000/price-api:sha-3f9c2e1
$ docker push localhost:5000/price-api:sha-3f9c2e1
3214acf345c0: Layer already exists
7c12895b777b: Layer already exists
sha-3f9c2e1: digest: sha256:034074b20fb92e756118038e8c32abeb0c269da12b78451263de0b83cdef6ccd size: 856
$ curl -s localhost:5000/v2/price-api/tags/list
{"name":"price-api","tags":["1.0.0","sha-3f9c2e1"]}

The second push uploaded nothing: layers are stored by their hash, and the registry already had them. Two tags, one digest.

Tags move, digests don't

A tag is a name that points at an image. A digest is the SHA-256 hash of the image's manifest: change one byte of content and the digest changes. Watch what happens when a different build is pushed as 1.0.0:

⤢ View

Same tag, different content, no warning. Only the digest is a promise.© Animation: DevOps Academy

Close

$ docker tag price-api:single localhost:5000/price-api:1.0.0
$ docker push localhost:5000/price-api:1.0.0
1.0.0: digest: sha256:367778fc7a085fc1131a5d04d26bb8ffb0e48d45bde2b5aa67bbd4bae48c7881 size: 856
$ docker pull localhost:5000/price-api@sha256:034074b20fb92e756118038e8c32abeb0c269da12b78451263de0b83cdef6ccd
Status: Downloaded newer image for localhost:5000/price-api@sha256:034074b2…

The registry accepted the overwrite without a word. A server that pulled 1.0.0 yesterday and one that pulls it today now run different code. The digest still fetches the original. Find an image's digest with docker buildx imagetools inspect localhost:5000/price-api:sha-3f9c2e1 or in the push output.

Docker Hub

Docker Hub is the default registry and home of the official images. Create a free account, then:

$ docker login -u yourname                    # prompts for a personal access token
$ docker tag price-api:multi yourname/price-api:1.0.0
$ docker push yourname/price-api:1.0.0

Use a personal access token from your account settings, not your password, and give it only the scope it needs (read-only for servers that just pull). Docker Hub limits how many images can be pulled per hour, with lower limits for anonymous pulls, so log in on CI runners and servers too; the current limits are in the usage and limits page linked below. Free accounts can keep public repositories, plus a limited number of private ones.

GHCR and ECR

Most teams keep images next to their code or their cloud. GitHub Container Registry (ghcr.io) uses your GitHub login and permissions:

$ echo "$GHCR_TOKEN" | docker login ghcr.io -u yourname --password-stdin
$ docker tag price-api:multi ghcr.io/yourname/price-api:1.0.0
$ docker push ghcr.io/yourname/price-api:1.0.0

In GitHub Actions, the job's own GITHUB_TOKEN can push, given permissions: packages: write (the CI/CD course builds this workflow). New packages are private until you change their visibility.

Amazon ECR gives each AWS account a registry, logged in to with a 12-hour token from the AWS CLI:

$ aws ecr create-repository --repository-name price-api --image-tag-mutability IMMUTABLE
$ aws ecr get-login-password --region eu-west-1 \
    | docker login --username AWS --password-stdin 123456789012.dkr.ecr.eu-west-1.amazonaws.com
$ docker tag price-api:multi 123456789012.dkr.ecr.eu-west-1.amazonaws.com/price-api:sha-3f9c2e1
$ docker push 123456789012.dkr.ecr.eu-west-1.amazonaws.com/price-api:sha-3f9c2e1

IMMUTABLE makes ECR reject a push to an existing tag, which turns the overwrite you saw above into an error. In CI, get AWS credentials through OIDC instead of stored keys (CI/CD course, lesson on secrets).

Tagging best practices

Deploy by digest, or by the SHA tag, never by a tag that moves. Then you can always say what's running, and a rollback means pointing back at an earlier digest that is still in the registry. Set a cleanup policy too: registries keep every untagged layer until you delete it, and storage costs money.

$ docker run -d --name registry -p 127.0.0.1:5000:5000 registry:3
$ docker tag price-api:multi localhost:5000/price-api:1.0.0
$ docker push localhost:5000/price-api:1.0.0 | tail -1              # note the digest
$ docker tag price-api:multi localhost:5000/price-api:sha-3f9c2e1
$ docker push localhost:5000/price-api:sha-3f9c2e1 | grep -c "already exists"
$ docker tag price-api:single localhost:5000/price-api:1.0.0
$ docker push localhost:5000/price-api:1.0.0 | tail -1              # a different digest
$ docker pull localhost:5000/price-api@sha256:<the first digest>
$ docker rm -f registry