How do I resolve Docker rate limit errors in GitHub Actions?

Last updated: October 22, 2025

Context

When running GitHub Actions that involve Docker image pulls, you may encounter the error: "toomanyrequests: You have reached your unauthenticated pull rate limit." This occurs when making multiple Docker image pull requests from Docker Hub without authentication.

Answer

To resolve Docker rate limit errors in your GitHub Actions pipeline, you need to authenticate with Docker Hub. Here's how to implement this:

  1. Add the Docker Hub login action to your GitHub Actions workflow:

    - uses: docker/login-action@v3
  2. Add the following step to make the Docker authentication available for Porter CLI commands:

    - name: Export Docker auth for child builds
      run: |
        AUTH_JSON=$(jq -c . "$HOME/.docker/config.json")
        echo "DOCKER_AUTH_CONFIG=$AUTH_JSON" >> "$GITHUB_ENV"
        echo "PORTER_DOCKER_AUTH_CONFIG=$AUTH_JSON" >> "$GITHUB_ENV"

If you continue to experience rate limit issues after implementing authentication, you can either:

  • Use an alternative public container registry

  • Subscribe to a Docker Hub paid plan for higher rate limits