To fix Docker Hub rate limit errors in CI, authenticate every pull with a Docker Hub account, reduce how many times each pipeline pulls the same image, and serve the images you depend on from a cache in front of Docker Hub. With Depot Registry's pull-through cache, you add Docker Hub as an upstream registry once and point your Dockerfiles and workflows at your Depot registry. Depot serves cached layers from its CDN and only goes back to Docker Hub for content it doesn't have. Depot CI and Depot GitHub Actions runners also start every job with its own public IP address, so jobs don't share one anonymous allowance.
Why CI hits Docker Hub rate limits
Docker Hub limits how many images a client can pull in a period of time. When a client goes over the limit, Docker Hub rejects the pull, and the job fails with a toomanyrequests error. The limits depend on your Docker plan and whether the pull is authenticated. Check Docker's usage and limits page for the current numbers rather than relying on a figure copied into a blog post or a config comment.
CI systems reach these limits faster than a developer laptop does, for three reasons:
- Anonymous pulls. A job that runs
docker pull, uses a public image as a service container, or builds from aFROMline without logging in counts against the anonymous limit, which is the lowest. - Shared egress IP addresses. Anonymous limits apply per IP address. When many jobs leave your network through the same NAT gateway or the same pool of self-hosted runners, they share one allowance. Jobs that each get their own address, like jobs on Depot CI and Depot GitHub Actions runners, don't.
- Many jobs pulling the same images. Ephemeral runners start with an empty image store. A matrix of test jobs, each starting a database container and building from the same base image, pulls those images again on every run.
A team that's growing feels this all at once. More engineers open more pull requests, each pull request runs more jobs, and the same base images get pulled many times an hour.
Authenticate every Docker Hub pull
Logging in is the smallest change. Authenticated pulls count against your Docker account instead of a shared IP address, and they get a higher limit. Create a Docker Hub access token, store it as a CI secret, and log in before any step that pulls from Docker Hub. In GitHub Actions, use docker/login-action:
- name: Login to DockerHub
uses: docker/login-action@v3
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}Put the login before the build step too. The Depot CLI uses your local Docker credentials, so a depot build whose Dockerfile pulls from Docker Hub uses the same login for FROM pulls. See Access private registries and the Docker Hub example for GitHub Actions.
Authentication raises the limit. It doesn't remove it. If every job still pulls every image, a busy pipeline can reach the authenticated limit too.
Reduce how many pulls each pipeline makes
Audit where your jobs pull from Docker Hub: FROM lines in Dockerfiles, services and container images in workflow files, Compose files used in tests, and scripts that call docker pull or docker run. Then cut the repeats:
- Pin image versions. Use a version tag or a digest instead of
latest. A pinned image changes only when you change it, which makes it safe to cache and reuse. - Use one base image per language. If five services build from five slightly different Node.js tags, consolidate on one. Fewer distinct images means fewer pulls and more cache hits.
- Build a shared CI image. Install the tools your jobs need into one image, push it to your own registry, and run jobs from it instead of pulling several public images and installing tools on every run.
- Pull from another public registry when the publisher provides one. Some Docker Hub images are also published in the Amazon ECR Public Gallery. It isn't a mirror of every Docker Hub image, so check that the image you need is there. See Docker images download again on every job.
The remaining pulls are the ones your pipeline genuinely needs. A pull-through cache keeps most of those from reaching Docker Hub.
Cache Docker Hub images with Depot Registry
A pull-through cache sits between your CI jobs and Docker Hub. Jobs pull from the cache. The first pull of an image fetches it from Docker Hub, and later pulls are served from the cache while the content is still there.
Depot Registry supports Docker Hub as an upstream. Pulls go through a Depot repository you create, and Depot authenticates to Docker Hub with credentials you enter once in the dashboard. Your CI jobs need only a Depot token, not Docker Hub credentials.
Add Docker Hub as an upstream registry
Create a Docker Hub access token first. Depot requires credentials for Docker Hub upstreams.
- Open Registry Settings in the Depot dashboard.
- Under Pull-through cache, click Add upstream registry.
- Select Docker Hub as the provider.
- Enter the registry URL
https://registry-1.docker.io, your Docker Hub username, and the access token. - Click Save upstream registry.
You can reuse this upstream registry for every Docker Hub image you want to cache.
Create a pull-through repository for each image
Each Depot repository mirrors one upstream repository path. For the official Node.js image, the upstream path is library/node.
- Open the Registry page and click Create repository.
- Enter the Depot repository name, such as
dockerhub/node. - Under Pull-through cache, click Configure.
- Select Existing registry and choose your Docker Hub upstream.
- Enter the upstream repository path,
library/node. - Click Create repository.
Repeat this for each image your pipelines pull often: base images, database images for service containers, and tool images. You can't add pull-through cache to an existing repository or change its upstream later, so pick the upstream path when you create it.
Pull through Depot in your jobs
Create a registry access token with Pull permission and list your pull-through repository names, such as dockerhub/node, in Repository scopes. Use the Depot repository name, not the Docker Hub path.
Change FROM lines to use your Depot registry hostname and repository name with the upstream tag:
FROM <org-id>.registry.depot.dev/dockerhub/node:<tag>In GitHub Actions, store the token as a secret and log in to your Depot registry before pulling or building. The username is x-token:
- name: Log in to Depot Registry
uses: docker/login-action@v3
with:
registry: <org-id>.registry.depot.dev
username: x-token
password: ${{ secrets.DEPOT_REGISTRY_PULL_TOKEN }}A login step doesn't cover job containers or service containers. GitHub Actions pulls those images before any step runs, so give them credentials in the workflow instead:
jobs:
test:
runs-on: ubuntu-latest
container:
image: <org-id>.registry.depot.dev/dockerhub/node:<tag>
credentials:
username: x-token
password: ${{ secrets.DEPOT_REGISTRY_PULL_TOKEN }}
services:
postgres:
image: <org-id>.registry.depot.dev/dockerhub/postgres:<tag>
credentials:
username: x-token
password: ${{ secrets.DEPOT_REGISTRY_PULL_TOKEN }}From a shell, log in and pull with Docker:
docker login <org-id>.registry.depot.dev -u x-token
docker pull <org-id>.registry.depot.dev/dockerhub/node:<tag>Replace <org-id> with your Depot organization ID. The registry also accepts an OIDC token from GitHub Actions when its identity matches a Depot project's trust relationship in the organization; GitHub Actions OIDC tokens must use the audience https://depot.dev. See Authentication and permissions.
How authentication works depends on where the job runs:
- Depot CI injects a short-lived
DEPOT_TOKENinto trusted jobs to authenticate container builds and access your organization's registry. Adepot buildwhoseFROMline references a pull-through repository needs no login step, and you don't need to store a Depot token or set up an OIDC trust relationship. See Depot CI authentication and Pulling private base images. Untrusted jobs, such as pull requests from forks, don't receive this token. - Depot GitHub Actions runners authenticate to Depot Registry like any other GitHub Actions job. Store a pull token as a secret and use the login step and
credentialsshown above, or use a GitHub Actions OIDC token that matches a trust relationship.
Know what the cache doesn't cover
The pull-through cache reduces traffic to Docker Hub. It doesn't replace Docker Hub as the source:
- Upstream outages. Content that isn't cached, or that was reclaimed, still has to come from Docker Hub. The cache doesn't guarantee pulls during an upstream outage.
- Reclaimed content. Pull-through blobs that aren't referenced by a pushed manifest become eligible for cleanup after 6 hours without repository access. The next pull after cleanup fetches them from Docker Hub again.
- The first pull. The first pull of an image can be slower, because Depot fetches the manifest and missing blobs from Docker Hub.
- Mutable tags. When a tag is already cached, Depot serves the cached manifest and doesn't check whether the tag now points to a different image upstream. Pulling
latestthrough the cache doesn't mean you get the newest upstream version. Use a version tag or digest when you need a specific release.
The pull-through cache documentation covers these details in Create a pull-through repository and Upstream tag updates.
Registry storage counts toward the same included storage as your build cache and Depot Cache. Check Registry pricing for the storage and transfer rates.
Where your runners' IP addresses come from
Anonymous limits apply per IP address, so the network your runners use matters. On Depot, every job starts with a unique public IP address. Each Depot CI job gets its own address, and by default each Depot GitHub Actions runner launches with a unique public IP address, so every job gets a different one. Services that rate-limit by IP address generally don't rate-limit those jobs as a group, so anonymous Docker Hub pulls from one job don't use up the allowance of the next. Authenticating and caching still matter: each job still pulls its images, and an authenticated limit applies per account, not per IP address. See Access private resources.
That changes if you need static IP addresses. Runners behind a NAT gateway share the same addresses, so Docker Hub is more likely to rate-limit them. If your runners leave through fixed IP addresses, whether on Depot or on your own infrastructure, authenticate pulls and use a pull-through cache.
Which fix to start with
- Add
docker/login-actionwith a Docker Hub access token to every job that pulls from Docker Hub, and addcredentialsto job and service containers that use Docker Hub images. This stops most anonymous-limit failures today. - If your jobs leave through a shared NAT gateway or a small pool of self-hosted runners, move them to infrastructure that gives each job its own public IP address, such as Depot CI or Depot GitHub Actions runners.
- List the images your pipelines pull, pin their versions, and remove duplicates.
- Create Depot Registry pull-through repositories for the images you pull most, and change
FROMlines and workflow image references to your Depot registry. Job and service containers needcredentialswith your Depot pull token. - Watch your CI logs for
toomanyrequests. If it still appears, find the job that pulls from Docker Hub directly and move that image behind the cache.
Keep Docker Hub credentials in the upstream registry configuration even after jobs pull through Depot. Depot uses them whenever it has to fetch content from Docker Hub.