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_dispatchaufruft. - 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_dispatchfür Ihren Branch. - Geplante Läufe verwenden für
GITHUB_REFden 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:
- 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.
- 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.
- 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. - Mindestintervall. Das kürzeste Intervall beträgt einmal alle 5 Minuten.
- 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. - Actions oder der Workflow deaktiviert, besonders bei Forks, wo geplante Workflows bis zur Aktivierung ausgeschaltet sind.
- 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
| Fehler | Ergebnis | Lösung |
|---|---|---|
Nicht in Anführungszeichen gesetztes /5 * * * | YAML-Parse-Fehler | Setzen Sie die Zeichenkette in Anführungszeichen |
| Annahme von Ortszeit | Läufe stundenweise daneben, verschieben sich mit der Sommerzeit | In UTC umrechnen |
0 0 31 * * | Läuft nur in Monaten mit 31 Tagen | Verwenden Sie 0 0 1 * * oder berechnen Sie den letzten Tag im Job |
| Tag des Monats und Wochentag sind beide gesetzt | Sie 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-Branch | Der Zeitplan wird nie ausgelöst | Auf den Standard-Branch mergen oder workflow_dispatch verwenden |
| Aufwendiger stündlicher Job zur Minute 0 | Verzögerte Starts, Ressourcenspitzen | Ungerade Minuten verwenden |
| Fehlende Concurrency | Überlappende Runs, wenn einer langsam ist | Fü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.
Verwandt
- TypeScript-Monorepo in GitHub Actions beschleunigenTypprüfung und Linting in TypeScript-Monorepos auf GitHub Actions beschleunigen: inkrementelles tsc, Projektreferenzen, Lint-Caches und parallele Jobs.
- Playwright im Monorepo mit GitHub Actions beschleunigenPlaywright-E2E-Tests in einem Node-Monorepo auf GitHub Actions beschleunigen: App einmal bauen, E2E überspringen, wenn sich die Web-App nicht ändert.
- CI-Geschwindigkeits-Badge in Ihre README einfügenZeigen Sie die Geschwindigkeit Ihrer CI mit einem README-Badge: die mediane Laufzeit Ihrer Repository-Workflows auf GitHub Actions, automatisch aktualisiert.
- Die besten Runner-Anbieter für GitHub Actions 2026Die besten GitHub-Actions-Runner-Anbieter nach Anwendungsfall: Preis, macOS, Docker-Builds, ARM, AWS, Flatrate. Preise Stand 22.10.2026.