Konfigurieren eines GitHub Actions-Workflows

  • 10 Minuten

Hier lernen Sie einige gängige Konfigurationen in einer Workflowdatei kennen. Außerdem untersuchen Sie die Kategorien von Ereignistypen, Deaktivieren und Löschen von Workflows sowie die Verwendung bestimmter Versionen einer Aktion für bewährte Methoden für Sicherheit.

Konfigurieren von Workflows zur Ausführung bei geplanten Ereignissen

Wie bereits erwähnt, können Sie Ihre Workflows so konfigurieren, dass sie ausgeführt werden, wenn eine bestimmte Aktivität auf GitHub ausgeführt wird, wenn ein Ereignis außerhalb von GitHub eintritt oder zu einem geplanten Zeitpunkt. Das schedule-Ereignis ermöglicht es Ihnen, die Ausführung eines Workflows zu bestimmten UTC-Zeiten auszulösen, wozu die POSIX-cron-Syntax verwendet wird. Diese cron-Syntax weist fünf *-Felder auf, und jedes Feld stellt eine Zeiteinheit dar.

Abbildung der fünf Felder mit Zeiteinheiten zum Planen eines Ereignisses in einer Workflowdatei

Wenn Sie beispielsweise alle 15 Minuten einen Workflow ausführen möchten, würde das schedule Ereignis wie im folgenden Beispiel aussehen:

on:
  schedule:
    - cron:  '*/15 * * * *'

Und wenn Sie einen Workflow jeden Sonntag um 3:00 Uhr ausführen möchten, sieht das schedule-Ereignis wie folgt aus:

on:
  schedule:
    - cron:  '0 3 * * SUN'

Sie können auch Operatoren verwenden, um einen Wertebereich anzugeben oder für die Einwahl bei Ihrem geplanten Workflow. Das kürzeste Intervall, in dem Sie geplante Workflows ausführen können, ist alle fünf Minuten, und sie werden beim neuesten Commit für den Standard- oder Basisbranch ausgeführt.

Konfigurieren von Workflows zur Ausführung bei manuellen Ereignissen

Zusätzlich zu geplanten Ereignissen können Sie einen Workflow mithilfe des workflow_dispatch-Ereignisses manuell auslösen. Dieses Ereignis gestattet Ihnen die Ausführung des Workflows mithilfe der GitHub-REST-API oder durch Auswählen der Schaltfläche Workflow ausführen auf der Registerkarte Aktionen in Ihrem Repository auf GitHub. Mit workflow_dispatch können Sie auswählen, auf welchem Branch der Workflow ausgeführt werden soll, und optionale inputs festlegen, die GitHub als Formularelemente in der Benutzeroberfläche präsentiert.

on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'     
        required: true
        default: 'warning'
      tags:
        description: 'Test scenario tags'

Zusätzlich zu workflow_dispatch können Sie die GitHub-API verwenden, um ein Webhook-Ereignis namens repository_dispatch auszulösen. Mit diesem Ereignis können Sie einen Workflow für Aktivitäten auslösen, die außerhalb von GitHub auftreten. Es dient im Wesentlichen als HTTP-Anforderung an Ihr Repository, in dem GitHub aufgefordert wird, einen Workflow von einer Aktion oder einem Webhook auszulösen. Wenn Sie dieses manuelle Ereignis verwenden, müssen Sie zwei Dinge tun: eine POST-Anforderung mit dem Webhook-Ereignisnamen im Anforderungstext an den GitHub-Endpunkt /repos/{owner}/{repo}/dispatches senden und Ihren Workflow für die Verwendung des repository_dispatch-Ereignisses konfigurieren.

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/dispatches \
  -d '{"event_type":"event_type"}'

on:
  repository_dispatch:
    types: [opened, deleted]

Konfigurieren von Workflows zur Ausführung bei Webhook-Ereignissen

Schließlich können Sie einen Workflow so konfigurieren, dass er ausgeführt wird, wenn bestimmte Webhook-Ereignisse in GitHub auftreten. Sie können die meisten Webhook-Ereignisse aus mehreren Aktivitäten für einen Webhook auslösen. Wenn für einen Webhook mehrere Aktivitäten vorhanden sind, können Sie einen Aktivitätstyp angeben, der den Workflow auslöst. Sie können z. B. einen Workflow für das check_run Ereignis ausführen, jedoch nur für die rerequested oder requested_action die Aktivitätstypen.

on:
  check_run:
    types: [rerequested, requested_action]

Repository_dispatch

repository_dispatch ist ein benutzerdefiniertes Ereignis in GitHub-Aktionen, mit dem externe Systeme (oder sogar andere GitHub-Workflows) Workflows manuell auslösen können, indem eine POST-Anforderung an die GitHub-API gesendet wird. Sie ermöglicht flexible Automatisierung und Integration mit externen Tools, Skripts oder Systemen, die Workflows in Ihrem Repository starten müssen.

Anwendungsfälle

  • Lösen Sie Workflows aus externen CI/CD-Tools aus.

  • Koordinieren Sie Multi-Repo-Bereitstellungen (z. B. Repo A beendet Build → löst Repo B aus).

  • Starten Sie die Automatisierung basierend auf externen Ereignissen (Webhooks, Überwachen von Warnungen, CRON-Aufträgen außerhalb von GitHub).

  • Verketten Sie Workflowausführungen zwischen Repositorys oder innerhalb von Monorepos.

Beispielworkflow, der auf repository_dispatch lauscht

name: Custom Dispatch Listener

on:
  repository_dispatch:
    types: [run-tests, deploy-to-prod]  # Optional filtering

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - name: Echo the payload
        run: |
          echo "Event type: ${{ github.event.action }}"
          echo "Payload value: ${{ github.event.client_payload.env }}"

Schlüsselelemente:

  • Typen: Optional. Definiert benutzerdefinierte Ereignistypen wie run-tests, deploy-to-produsw.

  • github.event.client_payload: Zugriff auf alle anderen benutzerdefinierten Daten, die im Dispatch-Ereignis übergeben werden.

  • github.event.action: Name der gesendeten event_type.

Auslösen des Ereignisses über API

Sie müssen eine POST-Anforderung an den GitHub REST API v3-Endpunkt senden:

POST https://api.github.com/repos/OWNER/REPO/dispatches

Autorisierung

  • Erfordert ein persönliches Zugriffstoken (PAT) mit Repositorybereich.
  • Stellen Sie für Organisationen die richtigen Zugriffseinstellungen für Ihr Token sicher.

Beispielbefehlsstruktur

curl -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: token YOUR_GITHUB_TOKEN" \
  https://api.github.com/repos/OWNER/REPO/dispatches \
  -d '{"event_type":"run-tests","client_payload":{"env":"staging"}}'

Nutzlaststruktur

{
  "event_type": "run-tests",
  "client_payload": {
    "env": "staging"
  }
}

Parameter

Feld Typ BESCHREIBUNG Erforderlich
event_type Schnur Ein benutzerdefinierter Name für das Ereignis. Dieser Name stellt eine Zuordnung zum Typenwert in Ihrem Workflow-Trigger her. Ja
client_payload Objekt Beliebige JSON-Nutzdaten zum Senden benutzerdefinierter Daten an den Workflow (github.event.client_payload) Nein

Repository_dispatch Parameteraufschlüsselung

Wenn Sie eine POST-Anforderung an den GitHub-API-Endpunkt senden, müssen Sie einen JSON-Textkörper mit zwei Hauptparametern übergeben:

  • Ereignistyp
  • client_payload
Ereignistyp

Eine erforderliche benutzerdefinierte Zeichenfolge, die Sie definieren. GitHub behandelt diesen Wert als "action" oder "type" des Dispatch. Es wird verwendet, um zu identifizieren, was den Workflow ausgelöst hat, und Workflows zu filtern, die auf bestimmte Typen reagieren.

  • Format:

    • Typ: Zeichenfolge
    • Beispiel: "deploy", "run-tests", "sync-db", "build-docker"

  • Verwendung in Workflow: Wird für die Überwachung bestimmter Ereignistypen und für den Zugriff auf den Wert innerhalb des Workflows verwendet. Dies unterstützt die Wiederverwendung eines einzelnen Workflows für mehrere Zwecke und macht die Automatisierung organisierter und ereignisgesteuerter.

  • Beispiel:

- name: Print event type
  run: echo "Event type: ${{ github.event.action }}"
client_payload

Ein freiformloses JSON-Objekt, mit dem Sie benutzerdefinierte Daten zusammen mit der Versendung senden können. Sie definieren die Struktur und können innerhalb des Workflows darauf zugreifen.

  • Format:

    • Typ: Objekt
    • Benutzerdefinierte Schlüssel und Werte

  • Verwendung in Workflow: Dieses Objekt wird für Bereitstellungen mit mehreren Umgebungen, versionsgesteuerte Versionen oder das Übergeben von Kontext aus einem anderen System oder einer anderen Pipeline verwendet und ermöglicht parametrisierte Workflows, ähnlich wie Eingabeargumente.

  • Beispiel:

- name: Show payload values
  run: |
    echo "Environment: ${{ github.event.client_payload.env }}"
    echo "Version: ${{ github.event.client_payload.version }}"
Beispiel für eine Nutzlastaufschlüsselung
{
  "event_type": "deploy-to-prod",
  "client_payload": {
    "env": "production",
    "build_id": "build-456",
    "initiator": "admin_user",
    "services": ["web", "api", "worker"]
  }
}

Verwenden bedingter Schlüsselwörter

In Ihrer Workflowdatei können Sie auf Kontextinformationen zugreifen und Ausdrücke auswerten. Obwohl Ausdrücke häufig mit dem bedingten Schlüsselwort if in einer Workflowdatei verwendet werden, um zu bestimmen, ob ein Schritt ausgeführt werden soll oder nicht, können Sie jeden unterstützten Kontext und Ausdruck verwenden, um ein bedingtes Schlüsselwort zu erstellen. Es ist wichtig zu wissen, dass Sie bei verwendung von Bedingten in Ihrem Workflow die spezifische Syntax ${{ <expression> }}verwenden müssen. Diese Syntax weist GitHub an, einen Ausdruck auszuwerten, anstatt ihn als Zeichenfolge zu behandeln.

Beispiel: Ein Workflow, der die bedingte Funktion if verwendet, um zu überprüfen, ob github.ref (Branch- oder Tagverweis, der die Workflowausführung ausgelöst hat) mit refs/heads/main übereinstimmt. Um fortzufahren, würde der Workflow ungefähr wie folgt aussehen:

name: CI
on: push
jobs:
  prod-check:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      ...

Beachten Sie, dass in diesem Beispiel die ${{ }} in der Syntax fehlen. Bei einigen Ausdrücken, z. B. der if bedingungsbedingten, können Sie die Ausdruckssyntax weglassen. GitHub wertet einige dieser gängigen Ausdrücke automatisch aus, aber Sie können Sie immer einschließen, wenn Sie vergessen, welche Ausdrücke GitHub automatisch von GitHub ausgewertet werden.

Weitere Informationen zur Workflowsyntax und zu Ausdrücken finden Sie unter Workflowsyntax für GitHub Actions.

Deaktivieren und Löschen von Workflows

Nachdem Sie Ihrem Repository einen Workflow hinzugefügt haben, liegt möglicherweise eine Situation vor, in der Sie den Workflow vorübergehend deaktivieren möchten. Sie können unterbinden, dass ein Workflow ausgelöst wird, ohne die Datei aus dem Repository löschen zu müssen. Dies erfolgt entweder auf GitHub oder über die GitHub-REST-API. Wenn Sie den Workflow erneut aktivieren möchten, können Sie dies problemlos mit denselben Methoden bewirken.

Screenshot des Deaktivierens eines Workflows auf GitHub

Das Deaktivieren eines Workflows kann in einigen der folgenden Situationen hilfreich sein:

  • Ein Fehler in einem Workflow erzeugt zu viele oder falsche Anforderungen, was sich negativ auf externe Dienste auswirkt.
  • Sie möchten einen Workflow vorübergehend anhalten, der nicht kritisch ist und in Ihrem Konto zu viele Minuten verbraucht.
  • Sie möchten einen Workflow anhalten, der Anforderungen an einen nicht aktiven Dienst sendet.
  • Sie arbeiten an einem Fork und benötigen nicht alle Funktionen einiger der darin enthaltenen Workflows (z. B. geplante Workflows).

Sie können auch eine laufende Workflowausführung in der GitHub-Benutzeroberfläche auf der Registerkarte Aktionen oder mithilfe des GitHub-API-Endpunkts DELETE /repos/{owner}/{repo}/actions/runs/{run_id} abbrechen. Beachten Sie, dass GitHub beim Abbrechen einer Workflowausführung alle Aufträge und Schritte in dieser Ausführung abbricht.

Verwenden eines vorlagenbasierten Workflows einer Organisation

Wenn Sie über einen Workflow verfügen, den mehrere Teams in einer Organisation verwenden, müssen Sie denselben Workflow für jedes Repository nicht erneut erstellen. Stattdessen können Sie Konsistenz in Ihrer Organisation fördern, indem Sie eine Workflowvorlage verwenden, die im Repository der Organisation .github definiert ist. Alle Mitglieder innerhalb der Organisation können einen auf einer Organisationsvorlage basierenden Workflow verwenden, und jedes Repository innerhalb dieser Organisation hat Zugriff auf diese Vorlagenworkflows.

Sie finden diese Workflows, indem Sie zur Registerkarte Aktionen eines Repositorys innerhalb der Organisation navigieren, Neuer Workflow auswählen und dann den Abschnitt mit den Workflowvorlagen der Organisation mit dem Titel „Von Organisationsname erstellte Workflows“ (Workflows created by „Organisationsname“) suchen. Beispielsweise verfügt die Organisation namens Mona über einen Vorlagenworkflow, wie hier gezeigt.

Screenshot eines vorlagenbasierten Organisationsworkflows namens „greet and triage by Mona“

Verwenden bestimmter Versionen einer Aktion

Wenn Sie in Ihrem Workflow auf Aktionen verweisen, wird empfohlen, dass Sie auf eine bestimmte Version dieser Aktion verweisen, anstatt auf die eigentliche Aktion. Indem Sie auf eine bestimmte Version verweisen, richten Sie eine Sicherung vor unerwarteten Änderungen ein, die in die Aktion gepusht werden, die den Workflow potenziell beschädigen könnten. Im Folgenden finden Sie mehrere Möglichkeiten, wie Sie auf eine bestimmte Version einer Aktion verweisen können:

steps:    
  # Reference a specific commit
  - uses: actions/setup-node@c46424eee26de4078d34105d3de3cc4992202b1e
  # Reference the major version of a release
  - uses: actions/setup-node@v1
  # Reference a minor version of a release
  - uses: actions/setup-node@v1.2
  # Reference a branch
  - uses: actions/setup-node@main

Einige Verweise sind sicherer als andere. Das Referenzieren eines bestimmten Branches führt beispielsweise dazu, dass diese Aktion auf den neuesten Änderungen aus diesem Branch basiert, was Sie möglicherweise wollen oder nicht. Wenn Sie auf eine bestimmte Versionsnummer oder den SHA-Hash eines Commits verweisen, geben Sie die Version der Aktion, die Sie ausführen, spezifischer an. Für höhere Stabilität und Sicherheit wird empfohlen, den Commit-SHA einer freigegebenen Aktion in Ihren Workflows zu verwenden.