Konfigurieren eines GitHub Actions-Workflows
Hier lernen Sie einige gängige Konfigurationen innerhalb einer Workflowdatei kennen. Außerdem erkunden Sie die Kategorien von Ereignistypen, das Deaktivieren und Löschen von Workflows sowie die Verwendung bestimmter Versionen einer Aktion für bewährte Sicherheitsmethoden.
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.
Wenn Sie beispielsweise einen Workflow alle 15 Minuten ausführen möchten, sieht das schedule-Ereignis wie folgt aus:
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. Mithilfe von workflow_dispatch können Sie den Branch auswählen, für den der Workflow ausgeführt werden soll, und optionale inputs festlegen, die GitHub als Formularelemente in der Benutzeroberfläche anzeigt.
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. Dieses Ereignis ermöglicht es Ihnen, einen Workflow durch eine Aktivität auszulösen, die außerhalb von GitHub erfolgt und im Wesentlichen als HTTP-Anforderung an Ihr Repository dient, um GitHub anzuweisen, einen Workflow aufgrund einer Aktion oder eines Webhooks 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. Die meisten Webhook-Ereignisse können von mehr als einer Aktivität für einen Webhook ausgelöst werden. Wenn also mehrere Aktivitäten für einen Webhook vorhanden sind, können Sie einen Aktivitätstyp angeben, um den Workflow auszulösen. Sie können z. B. einen Workflow für das check_run-Ereignis ausführen, aber nur für die Aktivitätstypen rerequested oder requested_action.
on:
check_run:
types: [rerequested, requested_action]
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 der Verwendung von bedingten Schlüsselwörtern in Ihrem Workflow die spezifische Syntax ${{ <expression> }} verwenden müssen, die GitHub anweist, einen Ausdruck auszuwerten, anstatt ihn als Zeichenfolge zu behandeln.
Beispielsweise sähe ein Workflow, der das bedingte Schlüsselwort if verwendet, um zu überprüfen, ob github.ref (der Branch- oder Tagverweis, der die Workflowausführung ausgelöst hat), mit refs/heads/main übereinstimmt, um mit den folgenden Schritten im Workflow fortzufahren, ungefähr wie folgt aus:
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, wie im Fall des bedingten Schlüsselworts if, dürfen 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.
Die Deaktivierung eines Workflows kann in einigen Situationen nützlich sein, z. B.:
- 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 Sie benötigen nicht alle Funktionen der Workflows, die darin enthalten sind (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 darin enthaltenen Aufträge und Schritte innerhalb dieser Ausführung abbricht.
Verwenden eines vorlagenbasierten Workflows einer Organisation
Wenn Sie über einen Workflow verfügen, der von mehreren Teams innerhalb einer Organisation verwendet wird, können Sie Konsistenz in Ihrer Organisation fördern, indem Sie eine Workflowvorlage verwenden, die im .github-Repository der Organisation definiert ist, anstatt denselben Workflow für jedes Repository neu zu erstellen. 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. Die Organisation namens „Mona“ hat beispielsweise einen Vorlagenworkflow, wie unten gezeigt.
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. Wenn Sie z. B. auf einen bestimmten Branch verweisen, wird diese Aktion aus den letzten Änderungen in diesem Branch ausgeführt, was Sie vielleicht beabsichtigen, oder auch 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.