Límite de pull de Docker Hub en GitHub Actions: soluciones
Última actualización
toomanyrequests: You have reached your pull rate limit significa que Docker Hub rechazó un docker pull porque el cliente alcanzó su límite, y en CI normalmente se trata de una descarga anónima desde una dirección IP compartida. La solución es iniciar sesión en Docker Hub en el workflow o descargar las mismas imágenes desde un mirror o registro que usted controle. Los límites indicados a continuación proceden de la documentación de uso de pulls de Docker, consultada en octubre de 2026.
El mensaje exacto
Error response from daemon: toomanyrequests: You have reached your pull rate limit.
You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limits
En la salida de BuildKit y de docker/build-push-action aparece como un 429 Too Many Requests en una línea FROM o en un paso resolve image config. El final exacto de la frase varía según la versión de Docker, pero el HTTP 429 y toomanyrequests se mantienen constantes.
Los límites actuales
Por ventana de 6 horas:
| Cliente | Pulls |
|---|---|
| Sin autenticar | 100 por dirección IPv4 o subred IPv6 /64 |
| Cuenta personal autenticada | 200 por cuenta |
| Pro, Team, Business | Ilimitados, sujeto a uso razonable |
Docker devuelve HTTP 429 cuando se alcanza el límite. Consulte la página antes de basarse en estas cifras, ya que Docker las ha modificado en el pasado.
Por qué CI alcanza el límite con tanta facilidad
- IP compartidas. Muchos trabajos de muchos clientes pueden salir por las mismas direcciones. Los pulls anónimos cuentan contra la IP, así que unos pocos de los suyos pueden ser la gota que colma el vaso.
- Muchos pulls por ejecución. Cada
FROM, contenedor de servicio ydocker runes un pull. Una matriz de 20 combinaciones que descarga 3 imágenes equivale a 60 pulls. - Sin inicio de sesión. Sin credenciales, comparte el presupuesto anónimo de la IP.
- Fallos de caché. Las máquinas virtuales nuevas en cada trabajo hacen que las imágenes se descarguen de nuevo cada vez.
Soluciones, en el orden en que conviene probarlas
1. Inicie sesión en Docker Hub
Cree un token de acceso de Docker Hub (Configuración de la cuenta, después Personal access tokens), guárdelo como secreto e inicie sesión antes de cualquier pull:
steps:
- uses: docker/login-action@v3
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
- uses: docker/setup-buildx-action@v3
- uses: docker/build-push-action@v6
with:
context: .
Esto le sitúa en el límite autenticado de su cuenta. Consulte el readme de docker/login-action para ver las opciones de registro. Tenga en cuenta que los secretos no están disponibles para los workflows activados por pull requests desde forks, por lo que esas ejecuciones siguen descargando de forma anónima.
2. Autentique los contenedores de servicio
Los bloques services y container de los trabajos descargan antes de que se ejecute ningún paso, así que proporcióneles credenciales directamente:
jobs:
test:
runs-on: ubuntu-latest
services:
postgres:
image: postgres:16
credentials:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
3. Descargue desde otro registro
Muchas imágenes oficiales están replicadas en otros lugares. Copiar sus imágenes base a GitHub Container Registry (GHCR) o a su registro en la nube elimina Docker Hub de la ruta. Las imágenes de GHCR se descargan con ghcr.io/OWNER/IMAGE, y en los workflows puede iniciar sesión con GITHUB_TOKEN:
- uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
Replique una vez con un workflow programado:
docker pull postgres:16
docker tag postgres:16 ghcr.io/OWNER/mirror/postgres:16
docker push ghcr.io/OWNER/mirror/postgres:16
Revise los términos de licencia de las imágenes que replique. Varios proveedores de nube también ofrecen mirrors públicos de las imágenes oficiales de Docker Hub; consulte la documentación del proveedor para conocer la dirección vigente.
4. Use una caché de pull-through
Un registro en modo pull-through (la imagen registry de Docker, o su registro en la nube) descarga desde Docker Hub una sola vez y sirve a los demás. Configure el daemon para usarlo como mirror:
sudo mkdir -p /etc/docker
echo '{"registry-mirrors": ["https://mirror.example.com"]}' | sudo tee /etc/docker/daemon.json
sudo systemctl restart docker
En los runners alojados por GitHub, reiniciar el daemon de Docker dentro de un trabajo no supone ningún problema. Consulte la documentación de mirrors de registro.
5. Descargue menos
- Almacene en caché las capas con BuildKit (
cache-fromycache-to) para no resolver las imágenes base desde cero. Consulte Caché de capas de Docker en CI. - Fije las imágenes por digest para no repetir la búsqueda de una etiqueta.
- Combine los trabajos que descargan la misma imagen, o guarde la imagen como artefacto una sola vez por workflow.
- No descargue imágenes que no utilice; revise los bloques
services.
6. Mejore el plan de Docker
Las cuentas Pro, Team y Business figuran como ilimitadas con uso razonable. Si su equipo descarga muchas imágenes, un plan de pago puede costar menos que el tiempo de ingeniería.
Elección del runner y límites de descarga
Los límites dependen de la identidad o de la IP, no del tipo de runner. En un proveedor de runners con máquinas dedicadas y cachés de capas de Docker ya calientes, se realizan menos pulls desde la propia máquina. Las máquinas de compiler.dev (8 vCPU / 16 GB, una máquina virtual nueva por trabajo) mantienen listas las cachés de capas de Docker, y puede cambiar con runs-on: [self-hosted, Linux, compiler-ci]; aun así, debería iniciar sesión en Docker Hub. Consulte los precios. Para la velocidad de construcción de imágenes Docker en concreto, los builders especializados como Depot son buenas opciones; consulte la comparativa.
Cómo prevenirlo
- Ejecute siempre
docker/login-actionantes de los builds y de los pulls. - Autentique los bloques
servicesycontainer. - Replique las imágenes base críticas en GHCR o en su propio registro.
- Use caché de capas y fije los digests.
- Configure alertas para los 429 en CI para detectarlos antes de que bloqueen una publicación.
Los errores de límite de tasa de la propia GitHub son otra cosa: consulte API rate limit exceeded. Las imágenes grandes también son una causa frecuente de No space left on device.
Preguntas frecuentes
¿Cuál es el límite de pulls de Docker Hub?
100 pulls cada 6 horas para usuarios no autenticados (por dirección IPv4 o IPv6 /64), y 200 cada 6 horas para cuentas personales autenticadas. Los planes Pro, Team y Business no tienen límite, sujeto a un uso razonable.
¿Los runners alojados en GitHub tienen un límite especial de Docker Hub?
No cuente con ello. Trate los pulls anónimos como limitados e inicie sesión.
¿Un pull fallido cuenta?
La documentación de Docker describe los límites en función de los pulls. Una petición que devuelve 429 no es un pull exitoso, pero los anteriores dentro de la ventana sí cuentan.
¿GHCR tiene límite de tasa?
GitHub Container Registry tiene sus propias políticas. Consulte la documentación de GitHub para conocer las reglas vigentes. Descargar imágenes públicas desde GHCR no utiliza los límites de Docker Hub.
Relacionado
- ¿Docker build lento en CI? Encuentre la causa y solúvala¿Builds de Docker lentos en CI? Revise el tamaño del contexto, .dockerignore, el orden de capas, fallos de caché y BuildKit. Corrija primero lo más costoso.
- Caché de capas de Docker en CI con BuildxAcelere los builds de Docker en GitHub Actions con cache-from y cache-to de buildx, los backends gha y registry, y un Dockerfile ordenado para aciertos de caché.
- Límite de API excedido en GitHub Actions: solucionesSolucione "API rate limit exceeded for installation ID" en GitHub Actions: GITHUB_TOKEN permite 1,000 solicitudes por hora por repo. Límites secundarios y soluciones.
- Plantilla de workflow de GitHub Actions para compilar DockerFlujo de trabajo de GitHub Actions para copiar y pegar: compile imágenes Docker con Buildx, capas en caché de GitHub y publique en GHCR desde main.