# Docker Hub rate limits: keep your builds pulling

> Docker Hub limits anonymous pulls. Pull its images through a CloudRepo proxy that signs in as your account, from Docker, GitHub Actions and GitLab CI.

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

You need a CloudRepo account. If you have none, [sign up](https://www.cloudrepo.io/signup) 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

Log in to your organization’s host alone, with your email address and a [repository token](/docs/authenticate/repository-tokens.html) that reaches the proxy:

**Terminal**

```bash
echo "$CLOUDREPO_TOKEN" | docker login your-org.mycloudrepo.io \
  --username you@example.com \
  --password-stdin
```

Expected: `Login Succeeded`.

## 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/`:

**Terminal**

```bash
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:

**Dockerfile**

```dockerfile
FROM your-org.mycloudrepo.io/repositories/docker-hub/library/alpine:latest
```

To write an official image without `library/`, see [Official images by short name](/docs/formats/docker.html#official-images-by-short-name). To add a sign-in to a proxy you already have, see [Upstream Credentials](/docs/consume/proxy-repositories.html#upstream-credentials).

## 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

Docker’s page [Docker Hub pull usage and limits](https://docs.docker.com/docker-hub/usage/pulls/) 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

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

Keep the repository token in a GitHub secret named `CLOUDREPO_TOKEN`, as [Store the token as a secret](/docs/ci/github-actions.html#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.yml`

```yaml
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 .
```

## In GitLab CI

Keep the repository token in a CI/CD variable named `CLOUDREPO_TOKEN`, as [Store the token as a variable](/docs/ci/gitlab-ci.html#store-the-token-as-a-variable) shows. The job logs in, then builds, and the `FROM` line pulls through the proxy:

`.gitlab-ci.yml`

```yaml
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](https://docs.gitlab.com/ci/docker/using_docker_images/#access-an-image-from-a-private-container-registry). For the Docker-in-Docker setup itself, see [Publish from GitLab CI](/docs/ci/gitlab-ci.html).

## 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:

**Terminal**

```bash
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](/docs/formats/docker.html#group-docker-repositories).

More on proxies, their sign-in and their settings: [Proxy Repositories](/docs/consume/proxy-repositories.html).

---

The page: https://www.cloudrepo.io/docs/ci/docker-hub-rate-limits.html
