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.
2. Log in to CloudRepo
Section titled “2. Log in to CloudRepo”Log in to your organization’s host alone, with your email address and a repository token that reaches the proxy:
echo "$CLOUDREPO_TOKEN" | docker login your-org.mycloudrepo.io \ --username you@example.com \ --password-stdinExpected: Login Succeeded.
3. Pull through the proxy
Section titled “3. Pull through the proxy”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/:
docker pull your-org.mycloudrepo.io/repositories/docker-hub/library/alpine:latestCloudRepo 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:
FROM your-org.mycloudrepo.io/repositories/docker-hub/library/alpine:latestTo 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.
How the proxy helps
Section titled “How the proxy helps”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.
What Docker Hub limits
Section titled “What Docker Hub limits”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.
Why CI runs into it
Section titled “Why CI runs into it”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.
In GitHub Actions
Section titled “In GitHub Actions”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:
name: Buildon: pushjobs: 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 .In GitLab CI
Section titled “In GitLab 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:
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:
docker pull your-org.mycloudrepo.io/repositories/team-registry/my-app:1.0.0When 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.