Each job pulls once, but the registry may not count per job. Anonymous pulls are counted per source address, and a runner fleet often leaves through one NAT gateway. A hundred small jobs can look like one heavy client. Fix it by authenticating, caching base images, and spreading pulls over time.
How the count actually works
Docker's documentation states that unauthenticated users on Docker Hub are limited to 100 pulls per IPv4 address (or IPv6 /64 subnet) in a 6 hour window. Authenticated personal accounts get 200 in the same window, and paid tiers are listed as unlimited, subject to fair use. Check the page for the current numbers before you plan around them, because limits change over time. We covered one such change in Docker Hub rate limit policy changes.
The part that surprises CI teams is the key. The limit is tied to an address or an account, not to a pipeline. If your runners share an egress IP, every anonymous pull from every team draws from the same bucket.
Why CI hits it first
A laptop pulls a handful of images a day. A CI fleet does something different.
- Ephemeral runners start with an empty local cache, so each job pulls its base images again.
- A matrix build multiplies one pipeline into many jobs, each pulling the same image.
- Multi-architecture images count once per architecture, according to Docker's definition of a pull.
- A burst after a merge freeze puts all of this into the same few minutes.
The result is a 429 response that looks random. One run passes, the next fails, and nothing in your code changed. If you want the general pattern behind this, read retry storms, because retrying a rate limited pull makes the next minute worse.
Three fixes, in order of effort
| Fix | What it changes | Cost to run |
|---|---|---|
| Authenticate every pull | Moves usage from the shared IP to an account with a higher allowance | Low, but you must manage the credential |
| Pull through your own cache | One upstream pull serves many jobs | Medium, you run a service |
| Copy base images into your own registry | Builds no longer depend on the public registry at pull time | Medium, plus a refresh routine |
Start with authentication, since it is quick. Use a token scoped for read access only and keep it out of pull request jobs that run untrusted code. Then add a pull-through cache so repeated pulls never reach the public registry. The trade-offs of that layer are in is a pull-through cache a security control or just speed and the settings are in pull-through cache proxy settings.
Check before you change anything
- Find the 429 responses in your job logs and note the time and the image.
- Confirm which egress address the runners use. If several teams share it, the bucket is shared.
- Count distinct base images across pipelines. A short list is a good candidate for copying into your own registry.
- Look for jobs that pull on every step instead of once per job.
Try it yourself
Click through it at your own pace, or open it full screen.
Click through the scan and look at how many base image layers a single image brings in. Each of those images is something your build pulls and trusts.
Where Safeguard fits
Once base images live in one place, you need to know what is inside them. Safeguard scans container images and their dependencies and builds an SBOM, so a cached image is not an unknown one. You can run a free scan at gold.safeguard.sh/scan.
Quick check
Does authenticating remove the limit?
Not always. Docker lists a higher allowance for authenticated personal accounts and unlimited pulls, subject to fair use, for paid tiers. Read the current table for your account type.
Do version checks count as pulls?
Docker's documentation says version checks do not count towards usage, while a pull that downloads a manifest does. A multi-architecture image counts once per architecture.
Sources
Last reviewed: 19 October 2026.
