Zum Inhalt springen

Was ist workflow_dispatch in GitHub Actions?

Zuletzt aktualisiert am

workflow_dispatch ist ein GitHub Actions Trigger, mit dem Sie einen Workflow manuell starten können, über den Actions-Tab, die GitHub CLI oder die REST API, optional mit typisierten Eingaben.

So funktioniert es

Fügen Sie workflow_dispatch unter on: hinzu und deklarieren Sie inputs, wenn Sie Parameter möchten. GitHub zeigt dann im Actions-Tab für diesen Workflow eine Schaltfläche "Run workflow" mit einer Branch-Auswahl und einem Formular für die Eingaben an. Im Workflow lesen Sie die Werte aus github.event.inputs oder dem inputs-Kontext.

Eingabetypen sind string, boolean, choice, number und environment. Eine choice-Eingabe benötigt eine Liste options. Sie können Eingaben als required markieren und ihnen einen default-Wert geben.

Die Workflow-Datei muss im Default-Branch vorhanden sein, damit die Schaltfläche erscheint. Anschließend können Sie den Workflow aber auch für einen anderen Branch ausführen.

Beispiel

on:
  workflow_dispatch:
    inputs:
      environment:
        description: Where to deploy
        type: choice
        options: [staging, production]
        default: staging
      dry_run:
        description: Skip the real deploy
        type: boolean
        default: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Deploying to ${{ inputs.environment }} (dry run: ${{ inputs.dry_run }})"

Starten Sie ihn über das Terminal:

gh workflow run deploy.yml -f environment=staging -f dry_run=false

Typische Einsatzzwecke

  • Deployments und Rollbacks mit einem Klick.
  • Erneutes Ausführen von Daten-Backfills oder Wartungsskripten.
  • Benchmark- oder Lasttests auf Abruf.
  • Testen eines zeitgesteuerten Jobs, ohne auf die Cron-Zeit zu warten. Siehe Cron-Zeitpläne.

Häufige Fehler

  • Workflow nicht im Default-Branch. Die Schaltfläche Run workflow erscheint erst, wenn die Datei zusammengeführt wurde.
  • Boolesche Eingaben als Strings verglichen. Im älteren Kontext github.event.inputs kommen Booleans als Strings an. Verwenden Sie besser den inputs-Kontext, der die Typen beibehält.
  • Zu viele Eingaben. Die API begrenzt die Anzahl der Eingaben, und lange Formulare fördern Fehler. Verwenden Sie sinnvolle Standardwerte.
  • Kein Schutz bei Produktions-Deployments. Jede Person mit Schreibzugriff kann einen Lauf starten. Kombinieren Sie das mit Schutzregeln für Environments.
  • Parallele Dispatches im Wettlauf. Zwei manuelle Deployments gleichzeitig können kollidieren. Verwenden Sie eine Concurrency-Gruppe.

workflow_dispatch wird während der Entwicklung oft auch genutzt, um einen wiederverwendbaren Workflow zu testen, zusammen mit workflow_call.

FAQ

Lässt sich workflow_dispatch mit anderen Triggern kombinieren?

Ja. Ein Workflow kann push, pull_request, schedule und workflow_dispatch gemeinsam auflisten. Eingaben werden nur bei manuellen Läufen gesetzt.

Worin unterscheiden sich workflow_dispatch und repository_dispatch?

workflow_dispatch richtet sich an einen bestimmten, benannten Workflow. repository_dispatch sendet ein benutzerdefiniertes Event an das Repository, und jeder Workflow, der auf diesen Event-Typ lauscht, wird ausgeführt.

Wer kann ihn auslösen?

Personen mit Schreibzugriff auf das Repository oder Tokens mit den passenden Berechtigungen.