Skip to content
Tutorials Center
My learning

Topics

Lesson 75 of 111 ยท Registries and CI/CD

Working with Registries

Learn how Docker registries work, how to read their names and auth flow, and how to log in safely to Docker Hub, GitHub, AWS, Google and Azure with credential helpers.

A registry is a server that stores images and hands them out on request. Every docker pull and docker push talks to one. You already use one all the time: if you never mention a registry, Docker means Docker Hub. But real projects use several. Public base images come from Docker Hub, your company's images live in a private registry, your CI pushes to the registry of your cloud provider, and open-source tools publish to GitHub or Quay.

This lesson explains what a registry really is (a small HTTP API), how to recognize the major ones from an image name, what happens when you authenticate, and how to log in without leaving passwords lying around. Pulls and the error messages below were run against the real public registries from Docker 29. Anything that needs an account, a cloud project or a secret (login, pushing to a cloud registry, tokens) is labelled read-only example, because it cannot be run safely on a shared machine.

What a registry is

A registry implements the OCI Distribution API: a handful of HTTP endpoints under /v2/. An image is stored as a manifest (a small JSON document that lists the layers and the configuration) plus the blobs (the layer archives themselves), each identified by its SHA-256 digest. Pulling means "get the manifest for this name and tag, then get every blob I do not already have".

TEXT
 docker pull ghcr.io/team/web:1.2
        |
        |  1. GET https://ghcr.io/v2/                  -> 401, "authenticate at ghcr.io/token"
        |  2. GET token for repository team/web (pull)  -> a short-lived bearer token
        |  3. GET /v2/team/web/manifests/1.2            -> manifest (layer digests)
        |  4. GET /v2/team/web/blobs/sha256:...         -> one request per missing layer
        v
 local image store

Because every registry speaks the same protocol, the Docker client does not care who runs it. You can see step 1 yourself with curl. The registry answers "who are you?" and tells the client where to get a token:

CONSOLE
$ curl -si https://registry-1.docker.io/v2/ | grep -iE 'www-authenticate|errors'
www-authenticate: Bearer realm="https://auth.docker.io/token",service="registry.docker.io"
{"errors":[{"code":"UNAUTHORIZED","message":"authentication required","detail":null}]}
$ curl -si https://ghcr.io/v2/ | grep -i www-authenticate
www-authenticate: Bearer realm="https://ghcr.io/token",service="ghcr.io",scope="repository:user/image:pull"

The client then requests a token from the realm URL and retries with an Authorization: Bearer ... header. Public images need no account: the token service hands out anonymous pull tokens. Private images require credentials when the token is requested. This two-step design is why a typo in a repository name often produces a confusing "denied" or "unauthorized" message rather than "not found": the registry will not even tell an anonymous caller whether a private repository exists.

Reading an image name

The first part of a name (if it contains a dot or a colon, or is localhost) is the registry host. Everything else is the repository path, then the tag or digest. All of these pulled successfully from public registries:

CONSOLE
$ docker pull -q ghcr.io/hlesey/busybox
ghcr.io/hlesey/busybox:latest
$ docker pull -q quay.io/prometheus/busybox
quay.io/prometheus/busybox:latest
$ docker pull -q gcr.io/distroless/static
gcr.io/distroless/static:latest
$ docker pull -q public.ecr.aws/docker/library/alpine:3
public.ecr.aws/docker/library/alpine:3
$ docker image ls --format 'table {{.Repository}}\t{{.Tag}}'
REPOSITORY                             TAG
public.ecr.aws/docker/library/alpine   3
quay.io/prometheus/busybox             latest
ghcr.io/hlesey/busybox                 latest

The same image can exist in several registries, and the contents are identical when the digest is identical. Compare the digest of Alpine as published on Docker Hub and as mirrored on Amazon's public gallery:

CONSOLE
$ docker buildx imagetools inspect public.ecr.aws/docker/library/alpine:3 | head -3
Name:      public.ecr.aws/docker/library/alpine:3
MediaType: application/vnd.oci.image.index.v1+json
Digest:    sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a

That be2656... digest is the one Docker Hub's alpine:3 resolved to at the time of writing (the digest changes whenever a new version is published). Content addressing makes the registry a dumb store: the digest is the identity, so a mirror cannot alter an image without changing it.

The registries you will meet

Registry Host Typical use
Docker Hub docker.io (implicit) Official images (alpine, postgres), public community images, private repos on a plan
GitHub Container Registry ghcr.io/<owner>/<image> Images next to your GitHub repository; authentication with a personal access token or GITHUB_TOKEN in Actions
GitLab Container Registry registry.gitlab.com/<group>/<project> Same idea for GitLab, with CI job tokens
Quay quay.io/<org>/<image> Red Hat ecosystem and many CNCF projects
Amazon ECR <account>.dkr.ecr.<region>.amazonaws.com/<repo> Images for AWS workloads (ECS, EKS, Lambda)
Google Artifact Registry <region>-docker.pkg.dev/<project>/<repo>/<image> Images for Google Cloud; the older gcr.io hosts are legacy, and gcr.io/distroless still serves public images
Azure Container Registry <name>.azurecr.io/<repo> Images for Azure services
Self-hosted any host Harbor, GitLab, the registry:2 image (Running a Private Registry)

Two more names come up in company settings. JFrog Artifactory (and similar repository managers such as Sonatype Nexus) stores Docker images next to Maven, npm and PyPI packages, and can act as a remote repository that caches Docker Hub for you. Docker clients see it as an ordinary registry, so docker login, docker pull and docker push work as usual; only the host name in the image reference changes (for example mycompany.jfrog.io/docker-local/app:1.0, a made-up host). One system for all artifacts simplifies permissions, retention rules and auditing. Harbor is an open-source registry that adds vulnerability scanning, image signing and replication between registries.

Pick the registry closest to where the image runs. Pulling from the same cloud and region is faster, cheaper (no data-transfer charges), and works with the platform's own permissions system. Most teams keep a single registry per environment and promote images between repositories (Tagging and Versioning Strategies).

Docker Hub limits pulls per hour for anonymous and free accounts. Busy CI systems often hit the limit and fail with "toomanyrequests". The usual cures are authenticating, using a pull-through cache or mirror, or mirroring the few base images you depend on into your own registry.

Errors, and what they mean

The wording of a failed pull tells you what went wrong. These were produced on purpose:

CONSOLE
$ docker pull alpine:no-such-tag
Error response from daemon: failed to resolve reference "docker.io/library/alpine:no-such-tag": docker.io/library/alpine:no-such-tag: not found
$ docker pull ghcr.io/no-such-owner/no-such-image:1
Error response from daemon: error from registry: denied
denied
$ docker pull myregistry.invalid/app:1
Error response from daemon: failed to resolve reference "myregistry.invalid/app:1": failed to do request: Head "https://myregistry.invalid/v2/app/manifests/1": dialing myregistry.invalid:443 container via direct connection because Docker Desktop has no HTTPS proxy: connecting to myregistry.invalid:443: dial tcp: lookup myregistry.invalid: no such host
$ docker pull 127.0.0.1:18199/app:1
Error response from daemon: failed to resolve reference "127.0.0.1:18199/app:1": failed to do request: Head "https://127.0.0.1:18199/v2/app/manifests/1": dial tcp 127.0.0.1:18199: connect: connection refused

Read them from the end:

  • not found: the registry is fine, the repository exists, but that tag does not. Check spelling and available tags.
  • denied / unauthorized: you are talking to the registry, but you may not see this repository. Either the name is wrong (private repositories hide their existence), or you need to log in.
  • no such host: the hostname does not resolve. A typo, a VPN you forgot, or DNS trouble (Troubleshooting Networks).
  • connection refused: the host exists but nothing listens on that port; the registry is down or you used the wrong port. Notice the URL starts with https://: Docker assumes TLS unless told otherwise.

The last part of the Docker Desktop message ("no HTTPS proxy") is specific to its networking and tells you the request went directly from the VM; on a corporate network the cause is often a proxy that must be configured (DNS, Proxies and Firewalls).

Logging in

Pushing to a registry, and pulling private images, requires docker login. The command stores credentials and sends them on later requests:

CONSOLE
$ docker login ghcr.io -u octocat --password-stdin < token.txt
Login Succeeded

(Read-only example. This lesson's author did not run docker login, because it would store a real credential on a shared machine.) Notice --password-stdin: it reads the secret from a file or a pipe, so it does not appear in your shell history or in the process list. Never type -p mypassword on the command line.

A few rules for credentials:

  1. Use tokens, not passwords. Docker Hub, GitHub and the other major registries issue access tokens with a limited scope (read-only, or write to one repository). A leaked token can be revoked without changing your account password.
  2. Give CI the smallest token that works: push to one repository for the build job, pull-only for production hosts.
  3. Do not reuse a personal login in CI. Create a bot account or use the platform's built-in identity (such as short-lived OIDC tokens in GitHub Actions).
  4. Log out on shared machines: docker logout ghcr.io.

Where the credentials go: credential helpers

By default, docker login writes the credential into ~/.docker/config.json as a Base64 string. Base64 is encoding, not encryption, so anyone who can read the file can read the secret. Docker warns about this and recommends a credential helper, a small program that stores the secret in the operating system's keychain instead. The relevant part of the file looks like this (this is the shape of the real file on a machine with Docker Desktop; the auths list is empty because nobody logged in):

JSON
{
  "auths": {},
  "credsStore": "desktop",
  "currentContext": "desktop-linux"
}

credsStore names the helper program (docker-credential-desktop on Docker Desktop, docker-credential-osxkeychain on macOS, docker-credential-wincred on Windows, docker-credential-secretservice or docker-credential-pass on Linux). When a helper is configured, auths only records which registries you logged into, and the secrets stay in the keychain. You can also set a helper for a single registry with credHelpers, which is how cloud providers integrate:

JSON
{
  "credHelpers": {
    "123456789012.dkr.ecr.eu-central-1.amazonaws.com": "ecr-login",
    "europe-docker.pkg.dev": "gcloud"
  }
}

The next sections are all read-only examples, since they require an account at each provider.

Docker Hub

Terminal
docker login -u yourname
docker tag web:1.0.0 yourname/web:1.0.0
docker push yourname/web:1.0.0

Docker Hub repositories live under your username or an organization. They are public unless created as private.

GitHub Container Registry (GHCR)

Create a personal access token with the write:packages scope (or use the built-in GITHUB_TOKEN inside Actions), then:

Terminal
echo "$GITHUB_TOKEN" | docker login ghcr.io -u USERNAME --password-stdin
docker tag web:1.0.0 ghcr.io/yourorg/web:1.0.0
docker push ghcr.io/yourorg/web:1.0.0

Image names must be lowercase. A package is private by default and can be linked to its repository so that repository permissions apply.

Amazon ECR

ECR does not use a static password. The AWS CLI exchanges your AWS identity for a token that lasts 12 hours:

Terminal
aws ecr get-login-password --region eu-central-1 \
  | docker login --username AWS --password-stdin 123456789012.dkr.ecr.eu-central-1.amazonaws.com

The repository must exist first (aws ecr create-repository --repository-name web), because ECR does not create repositories on push. The docker-credential-ecr-login helper automates the token refresh.

Google Artifact Registry

Terminal
gcloud auth configure-docker europe-docker.pkg.dev
docker push europe-docker.pkg.dev/my-project/my-repo/web:1.0.0

configure-docker adds a credHelpers entry like the one above; after that, normal docker push and docker pull use your Google identity.

Azure Container Registry

Terminal
az acr login --name myregistry
docker push myregistry.azurecr.io/web:1.0.0

az acr login obtains a token for the registry and passes it to Docker.

Practical habits

  • Always use the full name in automation. ghcr.io/yourorg/web:1.0.0 is unambiguous; a bare web:1.0.0 is not.
  • Pull by digest in production (image@sha256:...) if the registry can be changed by many people, and keep the tag for humans.
  • Mirror what you depend on. A copy of your base images in your own registry survives an outage or a deleted upstream repository.
  • Check which registry your cluster or Compose file uses, especially after copying examples between projects.
  • Use docker buildx imagetools inspect to look at any registry's manifest without pulling the image; it shows platforms and digests.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is a Docker registry, technically?

    A registry is an HTTP server under /v2/ that stores manifests and blobs identified by digest. Docker Hub, GHCR and ECR all speak the same protocol.
  2. 2. Which pull error most likely means you need to log in (or the name is wrong), rather than a missing tag?

    denied/unauthorized means the registry answered but refuses access. Private repositories also hide their existence, so a wrong name looks the same.
  3. 3. Why is docker login with --password-stdin better than -p?

    stdin keeps the secret out of the command line, which is visible in history and to other users running ps.
  4. 4. What is stored in ~/.docker/config.json when no credential helper is configured?

    Without a helper, credentials are Base64-encoded in the file. Anyone who can read it can decode the secret, which is why credential helpers exist.
  5. 5. Why did the same alpine:3 image show the same digest on Docker Hub and on public.ecr.aws?

    Images are content-addressed. A mirror that serves the same bytes necessarily reports the same digest, which also lets you verify it.

Summary

  • A registry is an HTTP server implementing the OCI Distribution API: manifests and blobs addressed by SHA-256 digest, with a token handshake for access.
  • The host in an image name tells you the registry: docker.io (implicit), ghcr.io, quay.io, *.amazonaws.com, *-docker.pkg.dev, *.azurecr.io.
  • Read pull errors from the end: not found (tag), denied (access or name), no such host (DNS), connection refused (port or server).
  • Log in with tokens and --password-stdin, never with a password on the command line; use a credential helper so secrets stay in the OS keychain.
  • Cloud registries use short-lived tokens obtained from the provider's CLI (aws ecr get-login-password, gcloud auth configure-docker, az acr login).
  • Give CI the minimum scope, mirror critical base images, and use full names (and digests) in automation.

Next: Running a Private Registry