GitHub Actions zeitgesteuert starten – pünktlich und überwacht

Einrichtung

Schritt für Schritt

1. Workflow für den Start von außen vorbereiten

   Ergänzen Sie in der Workflow-Datei unter on: den Auslöser workflow_dispatch. Den bisherigen schedule können Sie entfernen oder als Reserve stehen lassen. Wichtig: Die Datei muss auf dem Default-Branch liegen, sonst lässt sich der Workflow nicht von außen starten.

   # .github/workflows/nightly.yml
   name: Nightly
   on:
     workflow_dispatch:
     # schedule:
     #   - cron: '0 3 * * *'
   jobs:
     arbeit:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v7
         - run: ./scripts/nightly.sh

2. Ein Token mit dem Recht „Actions“ anlegen

   Legen Sie bei GitHub unter Settings → Developer settings → Personal access tokens ein Fine-grained token an. Wählen Sie nur dieses eine Repository und bei den Repository-Rechten Actions: Read and write. Mehr braucht der Start nicht. Unter Expiration legen Sie fest, wann das Token abläuft. Notieren Sie sich das Datum, denn danach antwortet GitHub mit einem Fehler und der Workflow startet nicht mehr.

3. Konto bei Cronjob.de anlegen

   Die Registrierung dauert eine Minute und kostet nichts. Fünf Cronjobs bleiben dauerhaft kostenlos; die ersten 14 Tage laufen im Unlimited-Tarif, inklusive Aufrufprotokoll mit der Antwort von GitHub.

   Kostenlos starten 14 Tage Unlimited inklusive, keine Zahlungsdaten

4. Cronjob mit der API-Adresse anlegen

   Als Adresse tragen Sie den Endpunkt mit Ihrem Namen, Ihrem Repository und dem Dateinamen des Workflows ein. Direkt vor der Adresse stellen Sie die Anfrage-Methode auf POST. Darunter erscheinen Content-Type (hier application/json) und Anfrage-Body, in den der Branch kommt. Unter Kopfzeilen kommen das Token und die Angabe zum Format hinzu.

   Adresse:            https://api.github.com/repos/IHR-NAME/IHR-REPO/actions/workflows/nightly.yml/dispatches
   Anfrage-Methode:    POST
   Content-Type:       application/json
   Anfrage-Body:       {"ref":"main"}
   Kopfzeilen:         Authorization: Bearer github_pat_…
                       Accept: application/vnd.github+json

5. Zeitplan wählen

   Wählen Sie den Takt, in dem der Workflow laufen soll, etwa täglich um 3:00 Uhr. Unsere Zeitpläne gelten in deutscher Zeit. GitHub rechnet ohne timezone-Angabe in UTC. Wer die Crontab-Syntax kennt, tippt sie direkt ein oder lässt den KI-Assistenten den Zeitplan aus einem Satz bauen.

   0 3 * * *

   Diesen Ausdruck können Sie bei Cronjob.de direkt so eintragen – das Zeitplanfeld versteht die Crontab-Schreibweise. Sie müssen sie aber nicht kennen: klicken Sie den Takt stattdessen einfach an.

6. Benachrichtigung einschalten

   Hinterlegen Sie unter Benachrichtigungen eine E-Mail-Adresse. Antwortet GitHub nicht mit Erfolg, etwa weil das Token abgelaufen ist, erfahren Sie es beim ersten Fehlschlag. Die Fehlerbenachrichtigung per E-Mail gibt es ab dem Tarif Plus, in den ersten 14 Tagen ist sie kostenlos dabei.

7. Optional: den Lauf selbst überwachen

   Der Start allein sagt noch nicht, ob der Workflow auch durchläuft. Legen Sie dafür einen Heartbeat an und lassen Sie den Workflow am Ende melden: bei Erfolg die Adresse, bei einem Fehler dieselbe Adresse mit /fail. Bleibt die Meldung aus oder kommt ein Fehler, warnen wir Sie. Das funktioniert auch, wenn Sie beim Zeitplan von GitHub bleiben: Stellen Sie den Spielraum dann großzügig ein, etwa eine Stunde, damit Verspätungen keinen Alarm auslösen, ein ausgefallener oder abgeschalteter Zeitplan aber schon.

         - name: Erfolg melden
           if: success()
           run: curl -fsS -m 10 --retry 3 https://runcheck.de/a8k3m2x9q1
         - name: Fehler melden
           if: failure()
           run: curl -fsS -m 10 --retry 3 https://runcheck.de/a8k3m2x9q1/fail

Was die fünf Felder eines Ausdrucks wie */5 * * * * bedeuten, steht in der Crontab-Referenz – mit Beispielen und den häufigsten Stolpersteinen. Bauen können Sie den Ausdruck im Crontab-Generator. Ob Sie dafür überhaupt einen Dienst von außen brauchen, zeigt der Vergleich der drei Wege.

Kontrolle

Läuft es wirklich?

Starten Sie den Cronjob einmal von Hand. Im Aufrufprotokoll von Cronjob.de steht dann Status 204 (leere Antwort, API-Version 2022-11-28) oder 200 mit Lauf-ID (API-Version 2026-03-10). Beides heißt: angenommen. Bei GitHub erscheint unter Actions ein neuer Lauf mit dem Auslöser workflow_dispatch. Steht dort nichts, liegt die Workflow-Datei meist nicht auf dem Default-Branch oder der Dateiname in der Adresse stimmt nicht.

FAQ

Häufige Fragen zu GitHub Actions

Warum startet mein geplanter Workflow nicht pünktlich?

Das Ereignis schedule verzögert sich laut GitHub bei hoher Last, besonders zur vollen Stunde, und eingereihte Läufe können ganz verworfen werden. Eine Zusage für den Zeitpunkt gibt es nicht. Wer pünktlich starten muss, lässt den Workflow per workflow_dispatch von außen starten.

Mein Zeitplan läuft gar nicht mehr.

Zwei häufige Ursachen: In einem öffentlichen Repository schaltet GitHub geplante Workflows nach 60 Tagen ohne Aktivität ab. Und geplante Workflows laufen nur auf dem Default-Branch. Liegt die Datei nur in einem anderen Branch, passiert nichts. Ein Heartbeat am Ende des Workflows meldet beides, weil das Lebenszeichen dann ausbleibt.

Welche Antwort von GitHub ist richtig?

Laut GitHub-Doku liefert die API-Version 2022-11-28 204 mit leerer Antwort, mit "return_run_details":true im Body 200. Die API-Version 2026-03-10 antwortet immer mit 200 und Lauf-ID. Die Version wählen Sie mit der Kopfzeile X-GitHub-Api-Version. Beides zählt bei uns als Erfolg.

Der Aufruf endet mit 401 oder 403.

401 heißt: Das Token fehlt, ist falsch geschrieben oder abgelaufen. 403 heißt meist: Dem Token fehlt das Recht Actions: Read and write für dieses Repository. Legen Sie ein neues Token an und tauschen Sie die Kopfzeile Authorization im Cronjob aus.

Der Aufruf endet mit 404 oder 422.

404: Name, Repository oder Dateiname in der Adresse stimmen nicht, das Token darf dieses Repository nicht sehen, oder die Methode steht nicht auf POST. GitHub antwortet bei privaten Repositories ohne gültige Anmeldung bewusst mit 404 statt 403. 422: Die Anfrage ist ungültig, meist fehlt ref im Body, der Branch existiert nicht oder der Workflow hat keinen Auslöser workflow_dispatch.

Kann ich dem Workflow Werte mitgeben?

Ja, über inputs im Anfrage-Body, etwa {"ref":"main","inputs":{"umgebung":"produktion"}}. Die Eingaben müssen im Workflow unter workflow_dispatch: beschrieben sein; GitHub erlaubt bis zu 25.

Wie oft kann ich einen Workflow so starten?

Bei uns bis zu jede Minute (ab Plus; im kostenlosen Tarif in 5-Minuten-Schritten), bei GitHubs eigenem Zeitplan höchstens alle fünf Minuten. In privaten Repositories zählt jeder Lauf auf die Actions-Minuten Ihres GitHub-Kontos. In öffentlichen Repositories sind Standard-Runner laut GitHub kostenlos.

Wie sicher ist das Token bei Ihnen?

Es steht nur in den Einstellungen Ihres Cronjobs. Beschränken Sie es trotzdem so weit wie möglich: ein Fine-grained Token, nur dieses eine Repository, nur das Recht Actions. Damit lässt sich nichts anderes tun, als diesen Workflow zu starten. Wird es nicht mehr gebraucht, widerrufen Sie es bei GitHub.