Verwenden von vordefinierten Bausteinen im Workflow

Aktionen sind die Bausteine deiner Workflows. Ein Workflow kann Aktionen enthalten, die von der Community erstellt wurden. Du kannst aber auch eigene Aktionen direkt im Repository deiner Anwendung erstellen. In diesem Leitfaden erfährst du, wie du Aktionen ermitteln, verwenden und anpassen kannst.

In diesem Artikel

Übersicht

Im Workflow können Sie vordefinierte Bausteine, sogenannte Aktionen, verwenden. Bei Aktionen handelt es sich um vordefinierte, wiederverwendbare Gruppen von Aufträgen oder Code, die bestimmte Aufgaben innerhalb eines Workflows ausführen.

Folgende Aktionen stehen zur Verfügung:

  • Wiederverwendbar: Aktionen können in verschiedenen Workflows und Repositorys verwendet werden, damit Sie ein und denselben Code nicht immer wieder neu schreiben müssen.
  • Vordefiniert: Viele Aktionen stehen im GitHub Marketplace zur Verfügung. Diese decken vielfältige Aufgaben wie das Auschecken von Code, das Einrichten von Umgebungen, das Ausführen von Tests und das Bereitstellen von Anwendungen ab.
  • Konfigurierbar: Sie können Aktionen mit Eingaben, Ausgaben und Umgebungsvariablen konfigurieren, um sie an Ihre jeweiligen Anforderungen anzupassen.
  • Communitygesteuert: Sie können eigene Aktionen erstellen und sie für andere freigeben oder Aktionen nutzen, die von der Community entwickelt wurden.

Die Aktionen, die du in deinem Workflow verwendest, können in den folgenden Instanzen definiert werden:

  • Im selben Repository wie dem deiner Workflowdatei
  • In einem internen Repository mit dem selben Unternehmenskonto, das zum Gewähren des Zugriffs auf Workflows konfiguriert ist
  • In einem beliebigen öffentlichen Repository
  • in einem veröffentlichten Docker-Container-Image auf Docker Hub

GitHub Marketplace ist eine zentrale Anlaufstelle für die Suche nach Aktionen, die von der GitHub-Community erstellt wurden. Auf der GitHub Marketplace-Seite kannst du Aktionen nach Kategorie filtern.

Wenn du über GHE.com auf GitHub zugreifst, kann es vorkommen, dass Aktionen, die hartcodierte API-Aufrufe an GitHub.com enthalten, nicht wie erwartet funktionieren.

Durchsuchen von Marketplace-Aktionen im Workflow-Editor

Direkt im Workflow-Editor deines Repositorys kannst du Aktionen suchen und durchstöbern und auch suchen. In der Seitenleiste kannst du nach einer bestimmten Aktion suchen, vorgestellte Aktionen anzeigen und vorgestellte Kategorien durchsuchen. Du kannst auch nach der Anzahl der Sterne schauen, die eine Aktion von der GitHub-Community erhalten hat.

  1. Navigiere in deinem Repository zu der Workflow-Datei, die du bearbeiten möchtest.
  2. Klicke zum Öffnen des Workflow-Editors oben rechts in der Dateiansicht auf .
    Screenshot einer Workflowdatei mit dem Headerabschnitt, das Stiftsymbol zum Bearbeiten von Dateien ist dunkelorange umrandet.
  3. Rechts vom Editor befindet sich die Sidebar GitHub Marketplace , um Aktionen zu durchsuchen. Bei Aktionen mit dem Badge wurde der oder die Ersteller*in von GitHub als Partnerorganisation bestätigt.
    Screenshot einer Workflowdatei im Bearbeitungsmodus, auf der rechten Randleiste befinden sich die Marketplace-Aktionen. Ein Häkchen in einem Stempelsymbol gibt an, dass der oder die Ersteller*in von GitHub überprüft wurde, und ist orange umrandet.

Hinzufügen einer Aktion zu deinem Workflow

Du kannst deinem Workflow eine Aktion hinzufügen, indem du in deiner Workflowdatei auf die Aktion verweist.

Du kannst die Aktionen, auf die in deinen GitHub Actions-Workflows verwiesen wird, im Abhängigkeitsdiagramm des Repositorys, in dem deine Workflows sich befinden, als Abhängigkeiten anzeigen. Weitere Informationen findest du unter Informationen zum Abhängigkeitsdiagramm.

Note

Um die Sicherheit zu erhöhen, unterstützt GitHub Actions keine Umleitungen für Aktionen oder wiederverwendbare Workflows. Dies bedeutet, dass bei einer Änderung des Besitzers bzw. der Besitzerin, des Namens des Repositorys einer Aktion oder des Namens einer Aktion alle Workflows, die diese Aktion mit dem vorherigen Namen verwenden, fehlschlagen.

Hinzufügen einer Aktion vom GitHub Marketplace

Die Listing-Seite einer Aktion enthält die Version der Aktion und die erforderliche Workflow-Syntax, um die Aktion zu benutzen. Damit dein Workflow auch bei Updates einer Aktion stabil bleibt, kannst du auf die zu verwendende Version der Aktion verweisen, indem du die Git- oder Docker-Tagnummer in deiner Workflowdatei angibst.

  1. Navigiere zu der Aktion, die du in deinem Workflow verwenden möchtest.
  2. Klicke hier, um das vollständige Marketplace-Angebot für die Aktion anzuzeigen.
  3. Klicke unter „Installation“ auf , um die Workflowsyntax zu kopieren.
    Screenshot des Marketplace-Angebots für eine Aktion, das Symbol „In Zwischenablage kopieren“ ist dunkelorange umrandet.
  4. Füge die Syntax als neuen Schritt in deinen Workflow ein. Weitere Informationen finden Sie unter Workflowsyntax für GitHub Actions.
  5. Lege in deinem Workflow Eingaben fest, wenn diese für die Aktion erforderlich sind. Weitere Informationen zu den für eine Aktion erforderlichen Eingaben findest du unter Verwenden von vordefinierten Bausteinen im Workflow.

Du kannst auch Dependabot version updates für die Aktionen aktivieren, die du deinem Workflow hinzufügst. Weitere Informationen findest du unter Deine Aktionen mit Dependabot auf dem neuesten Stand halten.

Hinzufügen einer Aktion aus demselben Repository

Wenn eine Aktion im selben Repository definiert wird, in dem deine Workflowdatei diese Aktion verwendet, kannst du entweder mit der {owner}/{repo}@{ref}- oder der ./path/to/dir-Syntax in deiner Workflowdatei auf die Aktion verweisen.

Beispiel für die Struktur einer Repository-Datei:

|-- hello-world (repository)
|   |__ .github
|       └── workflows
|           └── my-first-workflow.yml
|       └── actions
|           |__ hello-world-action
|               └── action.yml

Der Pfad ist relativ (./) zum Standardarbeitsverzeichnis (github.workspace, $GITHUB_WORKSPACE). Wenn die Aktion das Repository an einem anderen Speicherort als dem Workflow überprüft, muss der relative Pfad für lokale Aktionen aktualisiert werden.

Beispiel einer Workflow-Datei:

jobs:
  my_first_job:
    runs-on: ubuntu-latest
    steps:
      # This step checks out a copy of your repository.
      - name: My first step - check out repository
        uses: actions/checkout@v4
      # This step references the directory that contains the action.
      - name: Use local hello-world-action
        uses: ./.github/actions/hello-world-action

Die action.yml-Datei wird zum Bereitstellen von Metadaten für die Aktion verwendet. Weitere Informationen zum Inhalt dieser Datei findest du unter Metadatensyntax für GitHub Actions.

Hinzufügen einer Aktion aus einem anderen Repository

Wenn eine Aktion in einem anderen Repository als deine Workflowdatei definiert ist, kannst du mit der {owner}/{repo}@{ref}-Syntax in deiner Workflowdatei auf diese Aktion verweisen.

Die Aktion muss in einem öffentlichen Repository oder einem internen Repository gespeichert sein, das so konfiguriert ist, dass der Zugriff auf Workflows möglich ist. Weitere Informationen findest du unter Freigeben von Aktionen und Workflows in deinem Unternehmen.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: actions/setup-node@v4

Wenn du dich auf GHE.com aktiviert hat, kannst du mit dieser Syntax auf Aktionen innerhalb deines Unternehmens oder auf GitHub.com verweisen. GitHub Actions sucht die Aktion zunächst in deinem Unternehmen und anschließend auf GitHub.com.

Einen Container auf Docker Hub referenzieren

Wenn eine Aktion in einem veröffentlichen Docker-Containerimage auf Docker Hub definiert wird, musst du mit der docker://{image}:{tag}-Syntax in deiner Workflowdatei auf diese Aktion verweisen. Zum Schutz deines Codes und deiner Daten wird dringend empfohlen, die Integrität des Docker-Container-Images von Docker Hub zu verifizieren, bevor du es in deinen Workflow einfügst.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://alpine:3.8

Unter Workflow zu „Docker-image.yml“ und Creating a Docker container action (Erstellen einer Docker-Containeraktion) findest du einige Beispiele für Docker-Aktionen.

Sicherheitshärtung für die Verwendung von Aktionen in Ihren Workflows

GitHub bietet Sicherheitsfeatures, mit denen Sie die Sicherheit Ihrer Workflows erhöhen können. Sie können {die integrierten Features von GitHub verwenden, um sicherzustellen, dass Sie über Sicherheitsrisiken in den von Ihnen genutzten Aktionen benachrichtigt werden, oder um den Prozess der Aufbewahrung der Aktionen in Ihren Workflows auf dem neuesten Stand zu halten. Weitere Informationen findest du unter Verwenden der Sicherheitsfeatures von GitHub zum Sichern Ihrer Verwendung von GitHub-Aktionen.

Anwenden der Releaseverwaltung auf deine benutzerdefinierten Aktionen

Die Ersteller*innen einer Communityaktion können Tags, Branches oder SHA-Werte zum Verwalten der Releases der Aktion verwenden. Wie bei allen Abhängigkeiten solltest du die Version der zu verwendenden Aktion abhängig davon angeben, ob du mit automatischen Updates für die Aktion einverstanden bist.

Du legst die Version der Aktion in deiner Workflowdatei fest. Überprüfe die Dokumentation der Aktion, um Informationen zur Releaseverwaltung zu erhalten und zu erfahren, welches Tag, welcher Branch oder welcher SHA-Wert verwendet werden soll.

Note

Es wird empfohlen, beim Verwenden von Aktionen von Drittanbietern einen SHA-Wert zu nutzen. Es ist jedoch wichtig, zu beachten, dass Dependabot nur Dependabot alerts für anfällige GitHub Actions mit semantischer Versionsverwaltung erstellt. Weitere Informationen findest du unter Sicherheitshärtung für GitHub Actions und Informationen zu Dependabot-Warnungen.

Verwenden von Tags

Mit Tags kannst du entscheiden, wann zwischen Haupt- und Nebenversionen gewechselt werden soll. Diese sind jedoch kurzlebiger und können von den Verantwortlichen verschoben oder gelöscht werden. In diesem Beispiel wird gezeigt, wie du eine Aktion verwenden kannst, die als v1.0.1 getagged wurde:

steps:
  - uses: actions/javascript-action@v1.0.1

Verwenden von SHAs

Wenn du eine zuverlässigere Versionsverwaltung benötigst, solltest du den SHA-Wert verwenden, der der Version der Aktion zugeordnet ist. SHAs sind unveränderlich und daher zuverlässiger als Tags oder Branches. Bei diesem Ansatz erhältst du jedoch keine automatischen Updates für eine Aktion, einschließlich wichtiger Fehlerbehebungen und Sicherheitsupdates. Du musst den vollständigen SHA-Wert eines Commits verwenden, keinen abgekürzten Wert. Wenn du einen SHA auswählen, solltest du überprüfen, ob er aus dem Repository der Aktion und nicht aus einem Repositoryfork stammt. Dieses Beispiel zielt auf den SHA einer Aktion ab:

steps:
  - uses: actions/javascript-action@a824008085750b8e136effc585c3cd6082bd575f

Verwenden von Branches

Wenn du einen Zielbranch für die Aktion angibst, wird immer die Version ausgeführt, die sich aktuell auf diesem Branch befindet. Durch diesen Ansatz können Probleme entstehen, wenn ein Update für den Branch Breaking Changes enthält. In diesem Beispiel wird ein Branch namens @main verwendet:

steps:
  - uses: actions/javascript-action@main

Weitere Informationen finden Sie unter Informationen zu benutzerdefinierten Aktionen.

Verwenden von Eingaben und Ausgaben mit einer Aktion

Eine Aktion akzeptiert oder erfordert häufig Eingaben und generiert Ausgaben, die du verwenden kannst. Beispielsweise musst du bei einer Aktion einen Pfad zu einer Datei, den Namen einer Bezeichnung oder andere Daten angeben, die zur Aktionsverarbeitung verwendet werden.

Überprüfe die action.yml- oder action.yaml-Datei im Stammverzeichnis des Repositorys, um die Eingaben und Ausgaben einer Aktion anzuzeigen.

Bei action.yml definiert das Schlüsselwort inputs die erforderliche Eingabe namens file-path und enthält einen Standardwert, der verwendet wird, wenn sonst keiner angegeben wird. Das Schlüsselwort outputs definiert eine Ausgabe namens results-file, die angibt, wo die Ergebnisse zu finden sind.

name: "Example"
description: "Receives file and generates output"
inputs:
  file-path: # id of input
    description: "Path to test script"
    required: true
    default: "test-file.js"
outputs:
  results-file: # id of output
    description: "Path to results file"

Nächste Schritte

Weitere Informationen zu GitHub Actions findest du unter Grundlegendes zu GitHub Actions.