Skip to content
Tutorials Center
My learning

Topics

Lesson 81 of 111 ยท Registries and CI/CD

Docker Hub: Repositories, Automated Builds and Organizations

Use Docker Hub well: repositories and tags, official and verified images, organizations and teams, access tokens, pull rate limits, webhooks and automated builds.

Docker Hub is the default registry: when you write docker pull nginx, the name expands to docker.io/library/nginx and the client talks to Hub. Working with Registries explained what a registry is and how the protocol works. This lesson is about the product around it: how Hub organizes repositories, which images you can trust, how organizations and teams share access, what rate limits mean for your CI, and what automation Hub offers.

Docker changes plan names, limits and some features from time to time. The concepts here are stable, but check the Docker Hub pricing and documentation pages before you depend on a specific number. The rate-limit values below were read from the live service when this lesson was written. Anything that needs an account is labelled read-only example.

Namespaces, repositories and tags

A Hub image name has three parts:

TEXT
 docker.io / nginx / nginx : 1.29
 registry    namespace repo   tag
  • A namespace is a user or an organization (acme). Official images live in the special namespace library, which Docker hides: nginx means library/nginx.
  • A repository (acme/web) holds all versions of one image.
  • A tag (1.29, latest) is a movable label for one image in the repository, as in Tags and Registries. The immutable identity is the digest.

You can look at a public repository through Hub's HTTP API, which is how the website itself works. The reply is JSON with the description, star count, pull count and when the image was last updated:

CONSOLE
$ curl -s https://hub.docker.com/v2/repositories/library/alpine/
{"user":"library","name":"alpine","namespace":"library","repository_type":"image","status":1,"status_description":"active","description":"A minimal Docker image based on Alpine Linux with a complete package index and only 5 MB in size!","is_private":false,...

Hub's repository pages also show the available tags, the supported platforms (see Multi-Platform Images), the layers of each image and, with Scout enabled, vulnerability summaries (Docker Scout and SBOMs).

The command line can search too:

CONSOLE
$ docker search --filter is-official=true --limit 4 --format 'table {{.Name}}\t{{.IsOfficial}}' postgres
NAME       OFFICIAL
postgres   [OK]

docker search finds repositories by name. It is useful for a quick look, but it tells you little about quality; read the repository page before you use an unknown image.

Which images can you trust?

Anyone with a free account can publish to their own namespace, so Hub contains great images and terrible ones. Hub marks the trustworthy categories with badges:

Badge Meaning
Docker Official Image Curated by Docker with upstream maintainers. Reviewed Dockerfiles, regular rebuilds, multi-platform, no namespace (postgres, python, nginx, alpine).
Verified Publisher A commercial vendor whose identity Docker verified (for example database or security companies).
Docker-Sponsored Open Source An open-source project whose images are free to pull and sponsored by Docker.

The unmarked rest is community content. Before using it, check who maintains it, whether a source repository and a Dockerfile are linked, when the image was last updated and whether it has more than a handful of pulls. The best habit is to prefer official images and to build your own from them, as described in Choosing Base Images and Image Security.

Official images follow predictable naming. A tag like python:3.13-slim combines version and variant; latest simply means "the default variant of the newest stable release", which is why Image Tagging Strategy tells you to pin versions.

Accounts, tokens and logging in

You need an account to push, to create private repositories, to get higher pull limits and to use organization features. In the terminal:

CONSOLE
$ docker login

This is a read-only example (it asks for credentials). Two rules protect the account:

  1. Do not type your password into scripts. Create an access token under Account settings, give it the narrowest scope that works (read-only for pulling, read-write for pushing, and so on), and use that. Tokens can be revoked individually without changing your password. Pipe the token in with --password-stdin so it never appears in your shell history:

    CONSOLE
    $ echo "$DOCKER_TOKEN" | docker login -u myuser --password-stdin
    
  2. Use a credential helper so that Docker stores the login in the OS keychain instead of a plain config.json (Working with Registries shows how).

Organizations can also create organization access tokens, which belong to the organization rather than to a person. These are the right choice for CI, because they keep working when an employee leaves.

Pull rate limits

Docker Hub limits how many image pulls one client can make in a period. The limits depend on who you are:

  • Anonymous pulls are counted per source IP address.
  • Authenticated pulls on a free account are counted per account, with a higher allowance.
  • Paid plans have much higher or unlimited allowances (fair-use rules apply).

You can read your current allowance from response headers. A special repository exists for this, and a HEAD request for its manifest does not count as a pull. This is the real output from an anonymous request (the IP address header is omitted):

CONSOLE
$ TOKEN=$(curl -s "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" | sed 's/.*"token":"\([^"]*\)".*/\1/')
$ curl -sI -H "Authorization: Bearer $TOKEN" https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest | grep -i ratelimit
ratelimit-limit: 100;w=3600
ratelimit-remaining: 100;w=3600

Read 100;w=3600 as "100 pulls per window of 3,600 seconds". When this lesson was written the anonymous allowance was 100 pulls per hour per IP address; the numbers have changed in the past, so run the command yourself. When you exceed the limit, pulls fail with 429 Too Many Requests and the message toomanyrequests: You have reached your unauthenticated pull rate limit.

This matters more than people expect. A CI system where hundreds of jobs share a few IP addresses, or an office behind one NAT, burns through an anonymous allowance quickly. Remedies:

  • Log in in CI with an access token (account-based limits are separate from the IP).
  • Cache base images: reuse the build cache (Build Optimization) and avoid --pull on every run.
  • Use a pull-through cache or a private mirror (Private Registry), so repeated pulls hit your own server.
  • Copy the few base images you depend on into your own registry, or pull them from a mirror like public.ecr.aws/docker/library/..., which holds the official images too.
  • Keep Kubernetes nodes from pulling the same image on every pod start (use imagePullPolicy: IfNotPresent and a mirror).
flowchart LR
    CI["CI jobs<br/>many, same IP"] --> M{"Pull-through cache<br/>in your network"}
    M -- "cache hit" --> CI
    M -- "miss: one authenticated pull" --> H["Docker Hub"]
    H --> M

A pull-through cache turns hundreds of identical pulls into one request to Hub, so the rate limit stops being a problem.

Repositories you own

Create a repository from the website or by pushing to a new name under your namespace (Hub creates it on the first push, public by default for most accounts, so check the visibility setting). A typical publish flow:

CONSOLE
$ docker build -t acme/web:1.0.0 .
$ docker push acme/web:1.0.0
$ docker tag acme/web:1.0.0 acme/web:1.0
$ docker push acme/web:1.0

These are read-only examples because they need your account. Things to configure on a repository:

  • Visibility: public (anyone can pull) or private (only collaborators). Plans differ in how many private repositories they include.
  • Description and README: Hub renders Markdown. Say what the image contains, which tags exist, which ports and volumes it uses and how to configure it.
  • Categories and metadata: help people find it in search.
  • Immutable tags: an option on supported plans that stops anyone from overwriting a tag once pushed. It prevents the classic accident of re-pushing 1.0.0 with different content and is a good fit for release tags.
  • Collaborators: personal accounts can add collaborators to a private repository. For real teams, use an organization instead.

Organizations and teams

An organization is a shared namespace with its own members, billing and repositories. Use it as soon as more than one person (or more than one machine identity) pushes images:

  • Owners manage the organization, billing and settings.
  • Teams group members. You grant a team a permission on each repository: read (pull), write (pull and push) or admin (manage the repository settings).
  • Members inherit permissions from their teams, so a new hire joins one team and gets access to the right repositories.
  • Organization access tokens give CI systems access without tying them to a person.
  • Larger plans add single sign-on, SCIM provisioning, audit logs, image access management (which public registries and images your developers may pull) and registry access management.

The principle is the same as in the rest of Security: give each person and each pipeline the smallest permission that does the job, and prefer tokens you can revoke.

Webhooks and automated builds

Webhooks let Hub call a URL after every successful push. A webhook receiver can then trigger a deployment, notify a chat, or start a security scan. The payload is JSON with the repository, the tag and the pusher. This is a read-only example of the shape:

JSON
{
  "push_data": { "tag": "1.0.0", "pusher": "ci-bot" },
  "repository": { "repo_name": "acme/web", "namespace": "acme", "name": "web" }
}

Hub also offers automated builds on paid plans: you link a GitHub or Bitbucket repository, define rules ("a push to main builds latest; a tag matching v* builds a tag of the same name") and Hub builds and publishes the image for you. Older tutorials push automated builds as the way to publish. In practice, most teams now build in their own CI system (see CI Pipelines) because it gives them control over caching, secrets, multi-platform builds and attestations, and then push to Hub (or elsewhere). Docker also offers a hosted build service called Docker Build Cloud that runs docker buildx build on remote machines with a shared cache; it plugs into the same CLI as a buildx builder.

If you only need "build on push", a CI workflow is typically five lines and keeps the build logic in your repository where it can be reviewed.

Practical tips

  • Pull official images by version tag and consider digests for production. latest changes under you.
  • Treat Hub like any third party: mirror what you cannot afford to lose. If a publisher deletes a repository, your builds break.
  • Keep an eye on image freshness. A popular tag that has not changed for years has probably stopped receiving security fixes.
  • Remove stale repositories and tokens. An old token with push rights is a risk.
  • Add a .dockerignore and review your build context before you push to a public repository, as secrets in layers are readable by everyone (Secrets Management).
  • If you publish an image others use, document it and publish provenance and SBOM attestations (Docker Scout and SBOMs).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does docker pull nginx actually pull?

    Without a registry, Docker means Docker Hub; without a namespace, the official namespace library; without a tag, latest.
  2. 2. What does the header ratelimit-limit: 100;w=3600 mean?

    The number before the semicolon is the allowed pulls and w= is the window length in seconds, so 100 pulls per hour for that client.
  3. 3. Which is the best credential for a CI job that pushes images from an organization?

    Tokens can be scoped and revoked, and organization tokens do not depend on one employee's account.
  4. 4. Your CI hits 'toomanyrequests' errors while pulling base images. Which fix helps most?

    Authenticating gives account-based limits, and a pull-through cache or mirror reduces the number of requests that reach Hub at all.

Summary

  • Hub names are registry/namespace/repository:tag; official images live in the hidden library namespace.
  • Trust badges (Official, Verified Publisher, Docker-Sponsored Open Source) help; everything else needs a check of maintainer, source and freshness.
  • Log in with scoped access tokens, ideally organization tokens for CI, and pipe them through --password-stdin.
  • Pull limits depend on being anonymous (per IP) or authenticated (per account); read them from the ratelimit-* headers and reduce pulls with logins, caches and mirrors.
  • Organizations give teams read/write/admin permissions on repositories; use them as soon as several people or pipelines push.
  • Webhooks notify other systems after a push; automated builds exist on paid plans, but most teams build in their own CI.

Next: Node.js Image Recipe