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@v4
         - 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. Achten Sie auf die Laufzeit: Ohne eigene Angabe läuft das Token nach 30 Tagen ab. Wählen Sie eine längere Laufzeit und notieren Sie sich das Datum.

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.

4. Cronjob mit der API-Adresse anlegen

   Als Adresse tragen Sie den Endpunkt mit Ihrem Namen, Ihrem Repository und dem Dateinamen des Workflows ein. Im Reiter Erweitert stellen Sie die Anfrage-Methode auf POST, den Content-Type auf application/json und schreiben in den Anfrage-Body den Branch. Unter Eigene 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"}
   Eigene 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, nicht in UTC wie bei GitHub. 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 eine Antwort mit Status 204 (oder 200, je nach API-Version von GitHub) – 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?

Status 204 No Content mit leerer Antwort, bei der neueren API-Version 200 mit den Daten des gestarteten Laufs. 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, oder das Token darf dieses Repository nicht sehen. 422: Der Workflow hat keinen Auslöser workflow_dispatch, oder den Branch aus ref gibt es nicht.

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. Denken Sie dabei an die Actions-Minuten Ihres GitHub-Kontos: Jeder Lauf verbraucht sie.

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.