Skip to main content

Overview

Blacksmith by default enables a local Docker registry mirrors across our fleet, which act as “pull through” caches for public Docker images. All Docker pulls on Blacksmith runners are routed through these mirrors, and they only need to hit Docker Hub once, to hydrate the cache. This pull hydrates that particular image into the registry mirror so that subsequent pulls, across organizations, are served through a node-local registry backed by our colocated cache store. This means common image pulls are substantially faster.
The Docker pull through mirror only caches public images. We do not cache private images.

Basics

Preventing rate limit errors

The other main benefit is that CI jobs across an organization will now not be pulling as frequently from the Docker Hub and will therefore not run into Docker Hub’s rate limits. Prior to the pull through caches, our customers would occasionally run into rate limit errors such as:
ERROR: toomanyrequests: Too Many Requests.
You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limits.
This became even more common occurence after Docker Hub’s new rate limits were introduced on April 1st, 2025 In case you continue to run into rate limit errors, please contact us at [email protected]. As a temporary workaround, authenticating with Docker Hub will allow your workflows to pull images with a much higher rate limit.
To authenticate with Docker Hub, you can use the docker login command with your Docker Hub username and password. Here’s an example of how to authenticate with Docker Hub:
    - name: Login to Docker Hub
      uses: docker/login-action@v2
      with:
        username: ${{ secrets.DOCKERHUB_USERNAME }}
        password: ${{ secrets.DOCKERHUB_PASSWORD }}

Authenticating service containers with Docker Hub credentials

If you’re using service containers in your workflows, you can authenticate with Docker Hub using the credentials option.
  jobs:
  build:
    services:
      redis:
        # Docker Hub image
        image: redis
        ports:
          - 6379:6379
        credentials:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_PASSWORD }}

Pricing

There is no additional cost for using this feature. For all other pricing, please visit our pricing page.
I