Prepare now: Docker Hub rate limits will impact GitLab CI/CD

On April 1, 2025, Docker will implement new pull rate limits to Docker Hub that may significantly impact CI/CD pipelines across the industry, including those running on GitLab. The most significant change is the 100 pulls-per-6-hours limit for unauthenticated users.

What's changing?

Starting April 1, Docker will enforce the following pull rate limits: | User type | Pull rate limit per hour | Number of public repositories | Number of private repositories | |-----------|----------------|--------------|------------------| | Business, Team, Pro (authenticated) | Unlimited (fair use) | Unlimited | Unlimited | | Personal (authenticated) | 200 per 6-hour window | Unlimited | Up to 1 | | Unauthenticated users | 100 per 6-hour window per IPv4 address or IPv6 /64 subnet | Not applicable | Not applicable |

This is particularly important because: * GitLab's Dependency Proxy currently pulls from Docker Hub as an unauthenticated user. * Most CI/CD pipelines that don't use the Dependency Proxy pull directly from Docker Hub as unauthenticated users. * On hosted runners for GitLab.com, multiple users might share the same IP address or subnet, making them collectively subject to this limit. ## How this impacts GitLab users **Impact on direct Docker Hub pulls** If your CI/CD pipelines directly pull images from Docker Hub without authentication, they will be limited to 100 pulls per six-hour window per IP address. For pipelines that run frequently or across multiple projects sharing the same runner infrastructure, this will quickly exhaust the limit and cause pipeline failures. **Impact on GitLab Dependency Proxy** The GitLab Dependency Proxy feature allows you to cache Docker images within GitLab to speed up pipelines and reduce external dependencies. However, the current implementation pulls from Docker Hub as an unauthenticated user, meaning it will also be subject to the 100 pulls-per-6-hours limit. **Impact on hosted runners** For hosted runners on GitLab.com, we use [Google Cloud's pull-through cache](https://cloud.google.com/artifact-registry/docs/pull-cached-dockerhub-images). This mirrors the commonly pulled images and allows us to avoid rate limits. Job images defined as `image:` or `services:` in your `.gitlab-ci.yml` file, are not affected by rate limits. Things are slightly more challenging whenever images are pulled within the runner environment. The most common use case to pull images during runner runtime is to build an image using Docker-in-Docker or Kaniko. In this scenario, the Docker Hub image defined in your `Dockerfile` is pulled directly from Docker Hub and is likely to be affected by rate limits. ## How GitLab is responding We're actively working on solutions to mitigate these challenges: * **Dependency Proxy authentication:** We've added support for Docker Hub authentication in the [GitLab Dependency Proxy feature](https://gitlab.com/gitlab-org/gitlab/-/issues/331741). This will allow the Dependency Proxy to pull images from Docker Hub as an authenticated user, significantly increasing the rate limits. * **Documentation updates:** We've updated our [documentation](https://docs.gitlab.com/user/packages/dependency_proxy/#configure-credentials) to provide clear guidance on configuring pipeline authentication for Docker Hub. * **Internal infrastructure preparation:** We're preparing our internal infrastructure to minimize the impact on hosted runners for GitLab.com. ## How you can prepare **Option 1: Configure Docker Hub authentication in your pipelines** For pipelines that pull directly from Docker Hub, you can configure authentication to increase your rate limit to 200 pulls per six-hour window (or unlimited with a paid Docker Hub subscription). Add Docker Hub credentials to your project or group CI/CD variables (not in your `.gitlab-ci.yml` file). Please refer to our [documentation on using Docker images](https://docs.gitlab.com/ci/docker/using_docker_images/#use-statically-defined-credentials) for detailed instructions on setting up the `DOCKER_AUTH_CONFIG` CI/CD variable correctly. **Option 2: Use the GitLab Container Registry** Consider pushing your frequently used Docker images to your [GitLab Container Registry](https://docs.gitlab.com/user/packages/container_registry/). This eliminates the need to pull from Docker Hub during CI/CD runs: 1. Pull the image from Docker Hub. 2. Tag it for your GitLab Container Registry. 3. Push it to your GitLab Container Registry. 4. Update your pipelines to pull from GitLab Container Registry. ``` docker pull busybox:latest docker tag busybox:latest $CI_REGISTRY_IMAGE/busybox:latest docker push $CI_REGISTRY_IMAGE/busybox:latest ``` Then in your `.gitlab-ci.yml`: `image: $CI_REGISTRY_IMAGE/busybox:latest` **Option 3: Use GitLab Dependency Proxy** GitLab's Dependency Proxy feature provides a way to cache and proxy Docker images, reducing external dependencies and rate limit issues. Current authentication options: * GitLab 17.10: Configure Docker Hub authentication for the Dependency Proxy using [GraphQL API](https://docs.gitlab.com/user/packages/dependency_proxy/#configure-credentials-using-the-graphql-api) * GitLab 17.11: Use the new UI-based configuration in your group's settings (already available on GitLab.com) Once authentication is properly configured, you can: 1. Configure Docker Hub credentials in your group's Dependency Proxy settings: - For GitLab 17.11+ (or current GitLab.com): Navigate to your group's settings > Packages & Registries > Dependency Proxy. - For GitLab 17.10: Use the GraphQL API to configure authentication. 2. Update your pipelines to use the Dependency Proxy URLs in your CI/CD configuration: `image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/busybox:latest` **Option 4: Consider a Docker Hub paid subscription** For organizations with heavy Docker Hub usage, upgrading to a paid Docker subscription (Team or Business) will provide unlimited pulls, which may be the most straightforward solution. ## Best practices to reduce Docker Hub rate limit impact Regardless of which option you choose, consider these best practices to minimize Docker Hub rate limit impact: * Use specific image tags instead of `latest` to avoid unnecessary pulls. * Consolidate your Docker files to use the same base images across projects. * Schedule less critical pipelines to run outside of peak hours. * Use caching effectively to avoid pulling the same images repeatedly. **Note:** According to Docker Hub [documentation](https://docs.docker.com/docker-hub/usage/pulls/#pull-definition), the pull count is incremented when pulling the image manifest, not based on image size or number of layers. ## Timeline and next steps **Now** * Implement authentication for direct Docker Hub pulls. * GitLab.com users can already configure Docker Hub authentication for the Dependency Proxy using either: * The GraphQL API, or * The UI in group settings * Self-managed GitLab 17.10 users can configure Dependency Proxy authentication using the GraphQL API.

April 1, 2025

• Docker Hub rate limits go into effect.

April 17, 2025

• GitLab 17.11 will be released with UI-based Dependency Proxy authentication support for self-managed instances.

We recommend taking action well before the April 1 deadline to avoid unexpected pipeline failures. For most users, configuring the Dependency Proxy with Docker Hub authentication is the most efficient long-term solution.

Have questions or need implementation help? Please visit this issue where our team is actively providing support.