Zum Inhalt springen

Docker Pull Rate Limit in GitHub Actions: Lösungen

Zuletzt aktualisiert am

toomanyrequests: You have reached your pull rate limit bedeutet, dass Docker Hub einen docker pull abgelehnt hat, weil der Aufrufer sein Limit erreicht hat. In CI ist das meist ein anonymer Pull von einer geteilten IP-Adresse. Die Lösung besteht darin, sich im Workflow bei Docker Hub anzumelden oder dieselben Images von einem Mirror oder einer Registry zu beziehen, die Sie selbst kontrollieren. Die Limits unten stammen aus den Docs zur Pull-Nutzung von Docker, Stand Oktober 2026.

Die genaue Meldung

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

In der Ausgabe von BuildKit und docker/build-push-action erscheint er als 429 Too Many Requests in einer FROM-Zeile oder in einem Schritt resolve image config. Der genaue Wortlaut variiert zwischen den Docker-Versionen, aber HTTP 429 und toomanyrequests bleiben gleich.

Die aktuellen Limits

Pro Zeitfenster von 6 Stunden:

AufruferPulls
Nicht authentifiziert100 pro IPv4-Adresse oder IPv6-/64-Subnetz
Authentifiziertes persönliches Konto200 pro Konto
Pro, Team, BusinessUnbegrenzt, vorbehaltlich der Fair-Use-Regeln

Docker antwortet mit HTTP 429, sobald das Limit erreicht ist. Prüfen Sie die Seite, bevor Sie sich auf diese Zahlen verlassen, da Docker sie in der Vergangenheit schon geändert hat.

Warum CI so schnell daran scheitert

  • Geteilte IPs. Viele Jobs von vielen Kunden können dieselben ausgehenden Adressen nutzen. Anonyme Pulls zählen gegen die IP, sodass wenige Pulls von Ihnen das Fass zum Überlaufen bringen können.
  • Viele Pulls pro Lauf. Jedes FROM, jeder Service-Container und jedes docker run ist ein Pull. Eine Matrix mit 20 Zellen, die je 3 Images zieht, ergibt 60 Pulls.
  • Keine Anmeldung. Ohne Zugangsdaten teilen Sie sich das anonyme Kontingent der IP.
  • Cache-Fehlschläge. Frische VMs für jeden Job bedeuten, dass Images bei jedem Lauf erneut gezogen werden.

Lösungen, in der Reihenfolge zum Ausprobieren

1. Bei Docker Hub anmelden

Erstellen Sie ein Docker-Hub-Zugriffstoken (Kontoeinstellungen, dann Persönliche Zugriffstoken), speichern Sie es als Secret und melden Sie sich vor jedem Pull an:

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: .

Damit wechseln Sie in das authentifizierte Limit Ihres Kontos. Die Registry-Optionen finden Sie in der readme von docker/login-action. Beachten Sie, dass Secrets für Workflows, die durch Pull Requests aus Forks ausgelöst werden, nicht verfügbar sind; diese Läufe ziehen weiterhin anonym.

2. Service-Container authentifizieren

services- und container-Blöcke eines Jobs laden Images, bevor ein Schritt läuft. Geben Sie ihnen deshalb die Zugangsdaten direkt mit:

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        credentials:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

3. Aus einer anderen Registry beziehen

Viele offizielle Images werden auch anderswo gespiegelt. Wenn Sie Ihre Basis-Images in die GitHub Container Registry (GHCR) oder Ihre Cloud-Registry kopieren, entfällt Docker Hub aus dem Pfad. GHCR-Images werden mit ghcr.io/OWNER/IMAGE bezogen, und in Workflows können Sie sich mit GITHUB_TOKEN anmelden:

- uses: docker/login-action@v3
  with:
    registry: ghcr.io
    username: ${{ github.actor }}
    password: ${{ secrets.GITHUB_TOKEN }}

Einmal per geplantem Workflow spiegeln:

docker pull postgres:16
docker tag postgres:16 ghcr.io/OWNER/mirror/postgres:16
docker push ghcr.io/OWNER/mirror/postgres:16

Prüfen Sie die Lizenzbedingungen der Images, die Sie spiegeln. Mehrere Clouds bieten außerdem öffentliche Spiegel der offiziellen Docker-Hub-Images an; die aktuelle Adresse entnehmen Sie der Dokumentation des Anbieters.

4. Einen Pull-Through-Cache nutzen

Eine Registry im Pull-Through-Modus (das Registry-Image von Docker oder Ihre Cloud-Registry) holt sich das Image einmal von Docker Hub und liefert es danach an alle anderen aus. Konfigurieren Sie den Daemon so, dass er sie als Mirror verwendet:

sudo mkdir -p /etc/docker
echo '{"registry-mirrors": ["https://mirror.example.com"]}' | sudo tee /etc/docker/daemon.json
sudo systemctl restart docker

Auf GitHub-gehosteten Runnern ist ein Neustart des Docker-Daemons innerhalb eines Jobs unproblematisch. Siehe die Docs zu Registry-Mirrors.

5. Weniger pullen

  • Cachen Sie Layer mit BuildKit (cache-from und cache-to), damit Basis-Images nicht jedes Mal neu aufgelöst werden. Siehe Docker-Layer-Caching in CI.
  • Fixieren Sie Images per Digest, damit eine Tag-Abfrage nicht wiederholt wird.
  • Kombinieren Sie Jobs, die dasselbe Image ziehen, oder speichern Sie das Image einmal pro Workflow als Artefakt.
  • Ziehen Sie keine Images, die Sie nicht verwenden; prüfen Sie die services-Blöcke.

6. Docker-Tarif upgraden

Pro-, Team- und Business-Konten sind unter Fair Use als unbegrenzt aufgeführt. Wenn Ihr Team viel pullt, kann ein kostenpflichtiger Tarif günstiger sein als der Entwicklungsaufwand.

Runner-Wahl und Rate-Limits

Rate-Limits richten sich nach Identität oder IP, nicht nach dem Runner-Typ. Bei einem Runner-Anbieter mit dedizierten Maschinen und warmen Docker-Layer-Caches verlassen weniger Pulls die Maschine überhaupt. Die compiler.dev-Maschinen (8 vCPU / 16 GB, frische VM pro Job) halten Docker-Layer-Caches bereit, und Sie wechseln mit runs-on: [self-hosted, Linux, compiler-ci]; trotzdem sollten Sie sich bei Docker Hub anmelden. Siehe Preise. Speziell für die Geschwindigkeit von Docker-Image-Builds sind spezialisierte Builder wie Depot starke Optionen; siehe den Vergleich.

So verhindern Sie den Fehler

  1. Führen Sie docker/login-action immer vor Builds und Pulls aus.
  2. Authentifizieren Sie services- und container-Blöcke.
  3. Spiegeln Sie kritische Basis-Images nach GHCR oder in Ihre eigene Registry.
  4. Cachen Sie Layer und fixieren Sie Digests.
  5. Richten Sie Alerts für 429-Fehler in der CI ein, damit Sie sie erkennen, bevor ein Release blockiert wird.

Rate-Limit-Fehler von GitHub selbst sind etwas anderes: siehe API rate limit exceeded. Große Images sind außerdem eine häufige Ursache für No space left on device.

FAQ

Wie hoch ist das Pull-Limit von Docker Hub?

100 Pulls pro 6 Stunden für nicht authentifizierte Nutzer (pro IPv4-Adresse oder IPv6 /64) und 200 pro 6 Stunden für authentifizierte persönliche Konten. Pro, Team und Business sind im Rahmen der Fair-Use-Regeln unbegrenzt.

Gibt es für GitHub-gehostete Runner ein eigenes Docker-Hub-Limit?

Verlassen Sie sich nicht darauf. Behandeln Sie anonyme Pulls als begrenzt und melden Sie sich an.

Zählt ein fehlgeschlagener Pull mit?

Die Docker-Dokumentation beschreibt die Limits anhand von Pulls. Eine Anfrage, die 429 zurückgibt, ist kein erfolgreicher Pull, die vorherigen Anfragen im Zeitfenster zählen jedoch weiterhin.

Unterliegt GHCR einem Rate Limit?

Die GitHub Container Registry hat eigene Richtlinien. Die aktuellen Regeln finden Sie in der Dokumentation von GitHub. Das Pullen öffentlicher Images aus GHCR unterliegt nicht den Limits von Docker Hub.