Skip to content

Docker Hub rate limits: keep your builds pulling

Docker Hub limits how often anonymous users and Docker Personal accounts can pull. Busy CI runs into that limit, and the build stops. This page shows the fix: pull Docker Hub’s images through a CloudRepo Docker proxy repository that signs in to Docker Hub as your account.

1. Create the proxy repository with your Docker Hub sign-in

Section titled “1. Create the proxy repository with your Docker Hub sign-in”

You need a CloudRepo account. If you have none, sign up first. In the admin portal, open Create repository. Choose Docker as the Format, Proxy as the Kind and Docker Hub as the Upstream. Name the repository docker-hub: the name is part of every image name you pull through the proxy.

Open Upstream sign-in and type your Docker Hub username under Username and a Docker Hub access token under Access token. Use an access token, not your Docker Hub password. Then select Create repository, and confirm your identity if the admin portal asks.

Used on this page only, never saved. Never enter a token or password here.

Log in to your organization’s host alone, with your email address and a repository token that reaches the proxy:

Terminallog in with a repository token
echo "$CLOUDREPO_TOKEN" | docker login your-org.mycloudrepo.io \
--username you@example.com \
--password-stdin

Expected: Login Succeeded.

An image’s name through the proxy is your host, repositories/, the proxy’s name, then the image’s name on Docker Hub. An official image’s name starts with library/:

Terminalpull an official image
docker pull your-org.mycloudrepo.io/repositories/docker-hub/library/alpine:latest

CloudRepo serves each manifest and layer of the pull itself, with no redirect to Docker Hub, so the pull talks to CloudRepo alone.

In a Dockerfile, put the same name on the FROM line:

Dockerfilebuild from the proxy
FROM your-org.mycloudrepo.io/repositories/docker-hub/library/alpine:latest

To write an official image without library/, see Official images by short name. To add a sign-in to a proxy you already have, see Upstream Credentials.

A CloudRepo Docker proxy repository pulls images from Docker Hub for your builds, and you gave it your Docker Hub sign-in. Docker Hub then counts the pulls CloudRepo makes for that repository against your account, not as anonymous pulls. A Docker Personal account has a limit too, as Docker’s sentence below says.

Your builds sign in to CloudRepo alone, with a repository token. They need no Docker Hub secret of their own.

Docker’s page Docker Hub pull usage and limits says: “Unauthenticated and Docker Personal users using Docker Hub will experience rate limits on image pulls.” That page lists the limit for each Docker plan.

When a pull is over the limit, Docker Hub answers 429 with this message. Docker says it “appears in the Docker CLI or in the Docker Engine logs”:

You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limits

Docker puts the registry’s error code in front of the message, so a build log reads toomanyrequests: You have reached your pull rate limit. and the rest of it. With Docker’s containerd image store, the line starts error from registry: instead.

A CI job that does not sign in to Docker Hub pulls as an unauthenticated user. Docker sets the limit for unauthenticated users “per IPv4 address or IPv6 /64 subnet”, so every job that pulls from the same address counts against one limit.

Keep the repository token in a GitHub secret named CLOUDREPO_TOKEN, as Store the token as a secret shows. Log in before the first pull, and the build’s FROM line pulls through the proxy:

.github/workflows/build.ymllog in, then build
name: Build
on: push
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- name: Log in to CloudRepo
env:
CLOUDREPO_TOKEN: ${{ secrets.CLOUDREPO_TOKEN }}
run: echo "$CLOUDREPO_TOKEN" | docker login your-org.mycloudrepo.io --username you@example.com --password-stdin
- name: Build
run: docker build -t my-app:ci .

Keep the repository token in a CI/CD variable named CLOUDREPO_TOKEN, as Store the token as a variable shows. The job logs in, then builds, and the FROM line pulls through the proxy:

.gitlab-ci.ymllog in, then build
build-image:
image: docker:29-cli
services:
- docker:29-dind
variables:
DOCKER_TLS_CERTDIR: "/certs"
script:
- echo "$CLOUDREPO_TOKEN" | docker login your-org.mycloudrepo.io --username you@example.com --password-stdin
- docker build -t my-app:ci .

The job’s own image: and services: are pulled by the GitLab runner, not by the script, so the script’s login does not reach them. To pull them through CloudRepo too, GitLab’s runner reads a DOCKER_AUTH_CONFIG CI/CD variable: see GitLab’s Access an image from a private container registry. For the Docker-in-Docker setup itself, see Publish from GitLab CI.

One name for your images and Docker Hub’s

Section titled “One name for your images and Docker Hub’s”

Put the proxy in a Docker group repository with a hosted Docker repository. One group name then serves your own images from the hosted repository and Docker Hub’s images through the proxy, and your builds log in once:

Terminalpull through a group
docker pull your-org.mycloudrepo.io/repositories/team-registry/my-app:1.0.0

When your hosted repository holds any tag of an image name, the group answers that name from your hosted repository alone. To create a group and for its full rules, see Group Docker repositories.

More on proxies, their sign-in and their settings: Proxy Repositories.

View as Markdown