Zum Inhalt springen

API-Ratenlimit überschritten in GitHub Actions: Lösungen

Zuletzt aktualisiert am

API rate limit exceeded for installation ID in einem GitHub Actions-Log bedeutet, dass ein Schritt die GitHub-API mit dem GITHUB_TOKEN des Workflows aufgerufen und das stündliche Kontingent aufgebraucht hat. Dieses Token ist auf 1.000 Anfragen pro Stunde und Repository begrenzt (15.000 für Ressourcen eines GitHub Enterprise Cloud-Kontos). Abhilfe schaffen weniger Aufrufe, das Zwischenspeichern von Ergebnissen, ein besseres Token zur Authentifizierung oder Wartezeiten, wenn GitHub dies vorgibt. Die Angaben stammen aus der Dokumentation zu den REST-API-Limits von GitHub, geprüft im Oktober 2026.

Die genaue Meldung

HttpError: API rate limit exceeded for installation ID 12345678.
403 API rate limit exceeded for installation. If you reach out to GitHub Support for help, please include the request ID ...
You have exceeded a secondary rate limit. Please wait a few minutes before you try again.
rate limit exceeded

Die erste Meldung betrifft das primäre Limit, das erreicht wird, wenn das Stundenkontingent erschöpft ist. Die Meldung „secondary rate limit“ bezieht sich auf Anfragemuster, nicht auf die Stundensumme. Verwandte Meldungen: API rate limit exceeded for user ID ... (ein persönliches Token) und API rate limit exceeded for <IP> (But here's the good news: Authenticated requests get a higher rate limit) (ein Aufruf ganz ohne Token).

Die geltenden Limits

AnmeldedatenLimit
Kein Token (pro IP)60 Anfragen pro Stunde
Persönliches Zugriffstoken (Benutzer)5.000 pro Stunde
GitHub-App-Installation5.000 pro Stunde, je nach Repositories und Benutzern bis zu 12.500
GITHUB_TOKEN in Actions1.000 pro Stunde und Repository
GITHUB_TOKEN, Enterprise-Cloud-Konto15.000 pro Stunde und Repository

Das Limit für GITHUB_TOKEN teilen sich alle Workflow-Läufe desselben Repositorys in derselben Stunde. Ein stark genutztes Repository mit vielen Jobs kann es aufbrauchen, selbst wenn jeder Job nur einige Dutzend Aufrufe macht.

Sekundärlimits laut Dokumentation: höchstens 100 gleichzeitige Anfragen, höchstens 900 Punkte pro Minute bei REST-Endpunkten und allgemein höchstens 80 inhaltserstellende Anfragen pro Minute sowie 500 pro Stunde. GitHub weist darauf hin, dass sich diese Werte ohne Vorankündigung ändern können.

Ursachen, nach Wahrscheinlichkeit sortiert

1. Eine Matrix oder viele Läufe rufen die API gleichzeitig auf

30 Matrix-Zellen, die jeweils 40-mal gh api oder eine Release-Action aufrufen, ergeben 1.200 Anfragen. Verlagern Sie den Aufruf in einen einzigen Job und teilen Sie das Ergebnis.

2. Schleifen über Listen

Der Klassiker: gh pr list und dann pro PR ein gh api. Verwenden Sie einen einzigen paginierten Aufruf oder GraphQL, das viele Felder in einer Anfrage bündelt.

- run: gh pr list --state open --json number,title,labels --limit 200
  env:
    GH_TOKEN: ${{ github.token }}

3. Werkzeuge, die Releases herunterladen oder Versionen prüfen

Versionsmanager und Setup-Actions, die über die Releases-API die neueste Version abfragen (asdf, nvm-Aliasse, setup-*-Actions mit latest), verbrauchen das Token. Fixieren Sie Versionen oder übergeben Sie ein Token, damit sie den Cache oder ein authentifiziertes Limit nutzen.

4. Ein Aufruf ohne Token

Nicht authentifizierte Aufrufe vom Runner teilen sich das IP-Limit des Runners von 60 pro Stunde. Übergeben Sie immer ein Token:

env:
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

5. Bots und Automatisierungen im selben Repository

Dependabot, Labeler, Bots für veraltete Issues und Release-Tools verbrauchen dasselbe Repository-Kontingent.

6. Sekundärlimit durch Anfragespitzen

Viele Kommentare, Issues oder Status in einer Schleife lösen das Sekundärlimit aus. Bremsen Sie mit einem kurzen sleep und führen Sie diese Aufrufe nie parallel aus.

Lösungen

Verbleibendes Kontingent prüfen

- run: gh api rate_limit --jq '.resources.core'
  env:
    GH_TOKEN: ${{ github.token }}

Laut Dokumentation sind die Antwort-Header x-ratelimit-remaining und x-ratelimit-reset (Epoch-Sekunden) die verlässliche Quelle.

Für umfangreiche Automatisierung ein GitHub-App-Token verwenden

Eine GitHub-App-Installation hat ein eigenes Kontingent von 5.000 pro Stunde (bei großen Installationen mehr), getrennt vom GITHUB_TOKEN des Repositorys. Die Action create-github-app-token erzeugt im Job ein solches Token:

- uses: actions/create-github-app-token@v1
  id: app
  with:
    app-id: ${{ vars.APP_ID }}
    private-key: ${{ secrets.APP_PRIVATE_KEY }}
- run: gh api repos/${{ github.repository }}/issues --paginate
  env:
    GH_TOKEN: ${{ steps.app.outputs.token }}

Beachten Sie, dass die Meldung zum Ratenlimit eines Installations-Tokens ebenfalls „installation ID“ enthält. Prüfen Sie daher, welches Token Ihr Schritt verwendet.

Bei Limits zurückhaltend agieren

Bei primären Limits warten Sie bis x-ratelimit-reset. Bei Sekundärlimits empfiehlt GitHub, retry-after zu beachten, falls vorhanden, andernfalls mindestens eine Minute zu warten und dann exponentiell zurückzufahren. Die Dokumentation warnt außerdem, dass das Weitersenden von Anfragen trotz Limit dazu führen kann, dass eine Integration gesperrt wird.

for i in 1 2 3 4; do
  gh api repos/OWNER/REPO/issues && break
  sleep $((30 * i))
done

Anfragen reduzieren

  • Verwenden Sie bedingte Anfragen mit ETag und If-None-Match; eine 304-Antwort zählt nicht gegen das primäre Limit.
  • Fordern Sie nur an, was Sie brauchen, mit per_page=100 und Filtern.
  • Cache API-Ergebnisse mit actions/cache, wenn sie sich selten ändern (siehe GitHub Actions Caching).
  • Plane Scheduled Jobs seltener ein und versetze die Cron-Zeiten (Cron-Builder).

Nicht dasselbe wie Docker- oder Cache-Limits

Wenn die Fehlermeldung toomanyrequests enthält, siehe Docker-Pull-Rate-Limit. Cache-API-Limits (Uploads pro Minute) sind davon getrennt; siehe Cache-Limits. Rate Limits gelten pro Token und hängen nicht von der Runner-Geschwindigkeit ab, daher ändert ein Wechsel des Runner-Anbieters nichts daran. Ein Anbieter wie compiler.dev verwendet für GitHub-API-Aufrufe weiterhin dein GitHub-Token.

So verhindern Sie den Fehler

  1. Verwende GITHUB_TOKEN nur für leichte Aufrufe und ein App-Token für umfangreiche Automatisierung.
  2. Führe API-Aufrufe in einem Job aus, nicht in jeder Matrix-Zelle.
  3. Bevorzuge GraphQL oder paginierte Listenabfragen gegenüber Schleifen über einzelne Elemente.
  4. Fixiere Tool-Versionen, damit Setup-Schritte die API nicht abfragen.
  5. Protokolliere am Ende stark ausgelasteter Workflows das verbleibende Kontingent, um Anstiege zu erkennen.

FAQ

Wie hoch ist das Rate Limit für das GITHUB_TOKEN?

1.000 Anfragen pro Stunde und Repository sowie 15.000 für Ressourcen eines GitHub Enterprise Cloud-Kontos.

Wie prüfe ich mein Rate Limit in einem Workflow?

Führe gh api rate_limit mit gesetztem GH_TOKEN aus oder lies den Header x-ratelimit-remaining aus einer beliebigen API-Antwort.

Was ist ein Secondary Rate Limit?

Ein Limit für Anfragemuster, etwa zu viele gleichzeitige oder inhaltserstellende Anfragen. Es kann greifen, obwohl noch stündliches Kontingent übrig ist.

Wird das Limit jede Stunde zurückgesetzt?

Ja, das Zeitfenster wird zum Zeitpunkt aus x-ratelimit-reset zurückgesetzt.