Zum Inhalt springen

Cron-Zeitpläne in GitHub Actions: UTC, Verzögerungen, Fallen

Zuletzt aktualisiert am

Ein geplanter Workflow sieht einfach aus, aber einige Regeln überraschen viele: Die Zeiten gelten in UTC, Läufe können verspätet starten oder ausfallen, und der Zeitplan funktioniert nur auf dem Standard-Branch. Dieser Leitfaden erklärt die Syntax und das Verhalten, das Sie einplanen sollten.

Die Syntax

on:
  schedule:
    - cron: "30 5 * * 1-5"   # 05:30 UTC, Monday to Friday
    - cron: "0 */6 * * *"    # every 6 hours, on the hour
  workflow_dispatch:         # lets you run it by hand too

Ein Cron-Ausdruck besteht aus fünf Feldern:

 minute (0-59)
 | hour (0-23)
 | | day of month (1-31)
 | | | month (1-12 or JAN-DEC)
 | | | | day of week (0-6 or SUN-SAT)
 | | | | |
 * * * * *

Supported operators: (any), , (list), - (range), / (step). GitHub uses POSIX cron syntax. Extensions from other systems, like @daily, L, ? or a seconds field, do not work. Quote the expression in YAML, because a leading is otherwise parsed as a YAML alias and the file is invalid.

Mit dem Cron-Builder wandeln Sie Zeitpläne in Alltagssprache in Ausdrücke um und sehen die nächsten Laufzeiten. So vermeiden Sie Fehler am einfachsten.

Standardmäßig gilt überall UTC

Standardmäßig wertet GitHub Zeitpläne in UTC aus. Laut der aktuellen GitHub-Dokumentation gibt es außerdem den optionalen Schlüssel timezone, der einen IANA-Zeitzonennamen erwartet (z. B. America/New_York). Prüfen Sie daher die Referenz zu den Events, bevor Sie sich auf die ältere Lösung mit zwei Zeitplänen weiter unten verlassen. Wenn Sie den Schlüssel nicht setzen, gibt es keine Umstellung auf Sommerzeit. Ein Job mit 0 9 * * * läuft um 09:00 UTC, was im Sommer 05:00 in New York entspricht, im Winter 04:00. Wenn Sie "09:00 Ortszeit, das ganze Jahr" brauchen, haben Sie zwei Möglichkeiten:

  • Planen Sie beide UTC-Stunden ein, die infrage kommen, und beenden Sie den Job in der falschen Stunde sofort:
on:
  schedule:
    - cron: "0 13 * * 1-5"   # 09:00 EDT
    - cron: "0 14 * * 1-5"   # 09:00 EST
jobs:
  report:
    runs-on: ubuntu-latest
    steps:
      - name: Only proceed at 09:00 New York time
        id: gate
        run: |
          hour=$(TZ=America/New_York date +%H)
          [ "$hour" = "09" ] && echo "go=true" >> "$GITHUB_OUTPUT" || echo "go=false" >> "$GITHUB_OUTPUT"
      - if: steps.gate.outputs.go == 'true'
        run: ./send-report.sh
  • Akzeptieren Sie zweimal im Jahr eine Verschiebung um eine Stunde und vermerken Sie das in einem Kommentar.

Zeitpläne sind nicht exakt

Laut GitHub-Dokumentation können geplante Workflows in Zeiten hoher Auslastung verzögert werden, und zu den Zeiten hoher Auslastung gehört der Beginn jeder Stunde. In der Praxis starten Jobs mit 0 * * * * häufig mehrere Minuten zu spät, und bei starker Last fallen gelegentlich Läufe aus. Deshalb gilt:

  • Meiden Sie die volle Stunde. Verwenden Sie ungerade Minuten wie 17 3 * * *. Das ist der einfachste Weg, Verzögerungen zu verringern.
  • Verlassen Sie sich nicht auf exakte Zeiten. Ein Workflow, der genau um 09:00 laufen muss, sollte durch etwas anderes ausgelöst werden, etwa einen Cloud-Scheduler, der die API workflow_dispatch aufruft.
  • Machen Sie Jobs idempotent. Verwenden Sie den Zeitraum, den sie verarbeiten (ein Fenster aus der Ereigniszeit des Laufs), statt "jetzt minus 1 Stunde". So liefert ein verspäteter oder wiederholter Lauf dasselbe Ergebnis.
  • Mindestintervall: Das kürzeste von GitHub unterstützte Intervall beträgt 5 Minuten. Für häufigere Ausführungen verwenden Sie einen anderen Auslöser oder einen dauerhaft laufenden Dienst.

Wo Zeitpläne ausgeführt werden

  • Ein geplanter Workflow läuft auf dem neuesten Commit des Standard-Branches. Die Workflow-Datei auf anderen Branches wird für die Planung ignoriert. Um eine Änderung zu testen, pushen Sie sie auf den Standard-Branch oder starten Sie den Workflow manuell mit workflow_dispatch für Ihren Branch.
  • Geplante Läufe verwenden für GITHUB_REF den Standard-Branch des Repositorys. Der Checkout holt daher standardmäßig den Standard-Branch, sofern Sie nichts anderes angeben.
  • Als Akteur gilt der Benutzer, der die Cron-Zeile in der Datei zuletzt geändert hat. Wird dieser Benutzer aus der Organisation entfernt, können Läufe ausbleiben. Committen Sie bei Bedarf eine geringfügige Änderung an der Cron-Zeile unter einem Dienstkonto.

Die 60-Tage-Regel

In öffentlichen Repositorys deaktiviert GitHub geplante Workflows automatisch, wenn 60 Tage lang keine Aktivität im Repository stattfand. Sie erhalten eine E-Mail und müssen den Workflow wieder aktivieren, entweder in der Actions-Oberfläche oder mit:

gh workflow enable schedule-workflow.yml

Laut GitHub-Dokumentation ist diese Regel bei privaten Repositorys nicht wirksam. Wenn Sie in einem ruhigen öffentlichen Repository auf einen Zeitplan angewiesen sind, fügen Sie einen Schritt hinzu, der ihn aktiv hält, etwa einen regelmäßigen Commit durch einen Bot, oder nutzen Sie einen externen Scheduler.

GitHub Actions-Zeitplan läuft nicht

Wenn Ihr Zeitplan nicht läuft oder das Problem "GitHub Actions-Zeitplan funktioniert nicht" nur zeitweise auftritt, prüfen Sie der Reihe nach Folgendes:

  1. Nur Standard-Branch. Geplante Workflows laufen auf dem neuesten Commit des Standard-Branches. Ein Workflow, der nur auf einem Feature-Branch existiert, wird nie ausgelöst.
  2. Die 60-Tage-Regel. In einem öffentlichen Repository werden geplante Workflows automatisch deaktiviert, wenn 60 Tage lang keine Aktivität stattfand. Aktivieren Sie sie im Tab Actions wieder.
  3. Syntax und Anführungszeichen. Ein ungültiger Cron-Ausdruck oder ein nicht in Anführungszeichen gesetztes führendes * macht den Workflow ungültig. Prüfen Sie ihn mit dem Cron-Builder und dem YAML-Checker.
  4. Mindestintervall. Das kürzeste Intervall beträgt einmal alle 5 Minuten.
  5. Verzögerungen durch Last. Läufe können bei hoher Last verspätet starten oder ausfallen, besonders zur vollen Stunde. Verwenden Sie ungerade Minuten wie 17.
  6. Actions oder der Workflow deaktiviert, besonders bei Forks, wo geplante Workflows bis zur Aktivierung ausgeschaltet sind.
  7. Verwechslung von UTC. Der Lauf hat möglicherweise zur UTC-Zeit stattgefunden und nicht zu Ihrer Ortszeit.

GitHub Actions-Zeitplan funktioniert nach einer Änderung nicht

Änderungen an der Cron-Zeile gelten ab dem Standard-Branch, sobald sie zusammengeführt sind, und der nächste Lauf richtet sich nach dem neuen Ausdruck. Fügen Sie workflow_dispatch: hinzu, damit Sie den Job-Ablauf testen können, ohne zu warten.

Häufige Fehler

FehlerErgebnisLösung
Nicht in Anführungszeichen gesetztes /5 * * *YAML-Parse-FehlerSetzen Sie die Zeichenkette in Anführungszeichen
Annahme von OrtszeitLäufe stunden­weise daneben, verschieben sich mit der SommerzeitIn UTC umrechnen
0 0 31 * *Läuft nur in Monaten mit 31 TagenVerwenden Sie 0 0 1 * * oder berechnen Sie den letzten Tag im Job
Tag des Monats und Wochentag sind beide gesetztSie werden mit OR verknüpft, nicht mit AND (POSIX-Verhalten)Setzen Sie nur eines und prüfen Sie im Job das andere
Testen auf einem Feature-BranchDer Zeitplan wird nie ausgelöstAuf den Standard-Branch mergen oder workflow_dispatch verwenden
Aufwendiger stündlicher Job zur Minute 0Verzögerte Starts, RessourcenspitzenUngerade Minuten verwenden
Fehlende ConcurrencyÜberlappende Runs, wenn einer langsam istFügen Sie concurrency mit einer Gruppe hinzu

Fügen Sie eine Concurrency-Gruppe hinzu, damit ein langsamer Run nicht mit dem nächsten überlappt:

concurrency:
  group: nightly-report
  cancel-in-progress: false

Kosten von Zeitplänen

Zeitpläne werden wie jeder andere Lauf abgerechnet, auch fehlgeschlagene. Ein 5-minütiger Job alle 15 Minuten ergibt auf Linux 480 abgerechnete Minuten im Monat, also etwa $2.88 bei $0.006 pro Minute, und das summiert sich über viele Repositories. Cron-Jobs, die auf etwas warten, lassen sich oft durch Event-Trigger ersetzen (push, release, repository_dispatch, Webhooks). Verwenden Sie außerdem timeout-minutes und setzen Sie eine günstige Vorprüfung an den Anfang, damit der Job bei fehlender Arbeit in Sekunden beendet wird. Siehe Reduzierung Ihrer GitHub Actions-Kosten und schätzen Sie die Nutzung mit dem Actions-Kostenrechner.

Sinnvolle Einsatzzwecke für Zeitpläne

  • Nächtliche vollständige Testläufe und die Suche nach instabilen Tests (siehe Umgang mit instabilen Tests).
  • Abhängigkeits- und Sicherheitsscans.
  • Cache-Vorwärmung für den Standard-Branch, damit PRs mit einem warmen Cache starten (Caching-Leitfaden).
  • Bereinigung veralteter Issues und Erstellung von Berichten.

FAQ

Kann ich in meiner Zeitzone planen?

GitHub dokumentiert ein optionales Feld timezone mit einem IANA-Zonennamen für Zeitplan-Einträge; prüfen Sie dies in der aktuellen Dokumentation für Ihren Tarif. Ohne dieses Feld rechnen Sie in UTC um oder planen zwei UTC-Zeiten und prüfen die Ortszeit wie oben gezeigt.

Warum läuft mein GitHub Actions-Zeitplan nicht?

Meist liegt es daran, dass der Workflow nicht auf dem Standard-Branch liegt, das Repository 60 Tage inaktiv war (öffentliche Repositories), die YAML ungültig ist oder der Run durch hohe Last verzögert wird. Siehe die Checkliste oben.

Warum funktioniert mein GitHub Actions-Zeitplan nur manchmal nicht?

GitHub warnt, dass geplante Events unter hoher Last verzögert oder verworfen werden können, besonders zu Beginn der Stunde. Wechseln Sie auf eine ruhigere Minute und gestalten Sie den Job so, dass ein verspäteter oder ausgefallener Run verkraftet wird.

Warum lief mein Zeitplan verspätet oder hat einen Run übersprungen?

GitHub warnt, dass Last geplante Runs verzögern kann, besonders zu Beginn der Stunde. Nutzen Sie ruhige Minuten und planen Sie mit Toleranz.

Kann ich mehrere Zeitpläne in einem Workflow haben?

Ja, listen Sie mehrere cron-Einträge auf. Mit github.event.schedule erkennen Sie, welcher ausgelöst hat.

Wie führe ich denselben Workflow manuell aus?

Fügen Sie workflow_dispatch: hinzu und nutzen Sie „Run workflow“ im Actions-Tab oder gh workflow run.

Probieren Sie es aus

Nutzen Sie den kostenlosen Cron-Builder, um die nächsten Laufzeiten zu prüfen, bevor Sie committen. Wenn geplante Jobs aufwendig sind, zeigt der Vergleichsmodus von compiler.dev, was derselbe nächtliche Job auf schnelleren Runnern kostet.

Diesen Workflow auf compiler.dev ausführen Keine Karte nötig · 200 kostenlose Minuten

Kostenlos testen