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. 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. 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 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 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. 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
• 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, 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.