Metadaten-Syntax für GitHub-Aktionen

Informationen zur YAML-Syntax für GitHub Actions

Für Docker- und JavaScript-Aktionen ist eine Metadatendatei erforderlich. Der Dateiname für die Metadaten muss entweder action.yml oder action.yaml sein. Die Daten in der Metadaten-Datei definieren die Eingaben, Ausgaben und der Haupteinstiegspunkt für die Aktion.

Aktionsmetadatendateien verwenden die YAML-Syntax. Wenn Sie bislang noch nicht mit YAML gearbeitet haben, lesen Sie den Artikel „Learn YAML in five minutes“.

name

Required (Erforderlich): Der Name Deiner Aktion. GitHub zeigt den name auf der Registerkarte Actions an, damit Du die Aktionen in jedem Auftrag visuell identifizieren kannst.

Autor

Optional: Der Name des Autors der Aktion.

Beschreibung

Erforderlich Eine kurze Beschreibung der Aktion.

inputs

Optional: Mit Eingabeparametern können Sie die Daten angeben, welche die Aktion während der Laufzeit erwartet. GitHub speichert Eingabeparameter als Umgebungsvariablen. Eingabe-IDs in Großbuchstaben werden während der Laufzeit in Kleinbuchstaben umgewandelt. Sie sollten Eingabe-IDs in Kleinbuchstaben verwenden.

Beispiel

In diesem Beispiel werden zwei Eingaben konfiguriert: „numOctocats“ und „octocatEyeColor“. Die Eingabe „numOctocats“ ist nicht erforderlich und entspricht standardmäßig dem Wert „1“. Die Eingabe „octocatEyeColor“ ist erforderlich und weist keinen Standardwert auf. Workflow-Dateien, die diese Aktion einsetzen, müssen das Stichwort with verwenden, um für „octocatEyeColor“ einen Eingabewert festzulegen. Weitere Informationen zu with-Syntax finden Sie unter „Workflow-Syntax für GitHub Actions“.

inputs:
  numOctocats:
    description: 'Number of Octocats'
    required: false
    default: '1'
  octocatEyeColor:
    description: 'Eye color of the Octocats'
    required: true

Wenn Sie eine Eingabe für eine Aktion in einer Workflow-Datei angeben oder einen Standardeingabewert verwenden, erstellt GitHub eine Umgebungsvariable für die Eingabe mit dem Namen INPUT_<VARIABLE_NAME>. Die erstellte Umgebungsvariable wandelt Eingabenamen in Großbuchstaben um und ersetzt Leerzeichen durch _-Zeichen.

Wenn beispielsweise ein Workflow die Eingaben „numOctocats“ und „octocatEyeColor“ definiert hat, kann der Aktionscode die Werte für die Eingaben mithilfe der Umgebungsvariablen INPUT_NUMOCTOCATS and INPUT_OCTOCATEYECOLOR lesen.

inputs.<input_id>

Erforderlich Ein Kennzeichner, der die Eingabe identifiziert, als string. Der Wert von <input_id> ist eine Übersicht zu den Metadaten der Eingabe. Die <input_id> muss im Objekt inputs als ein eindeutiger Kennzeichner vorhanden sein. Die <input_id> muss mit einem Buchstaben oder _ beginnen und darf nur alphanumerische Zeichen, - oder _ enthalten.

inputs.<input_id>.description

Erforderlich Eine Beschreibung des Eingabeparameters als String.

inputs.<input_id>.required

Erforderlich: Ein boolescher Wert, um anzugeben, ob für die Aktion der Eingabeparameter erforderlich ist. Legen Sie den Wert true fest, wenn der Parameter erforderlich ist.

inputs.<input_id>.default

Optional: Ein String, der den Standardwert darstellt. Der Standardwert wird verwendet, wenn ein Eingabeparameter in einer Workflow-Datei nicht angegeben ist.

outputs

Optional: Ausgabeparameter erlauben Dir, Daten zu deklarieren, die eine Aktion setzt. Aktionen, die in einem Workflow später ausgeführt werden, können die Ausgabedaten der zuvor ausgeführten Aktionen verwenden. Wenn beispielsweise eine Aktion vorliegt, die zwei Eingaben addiert hat (x + y = z), kann die Aktion die Summe (z) für andere Aktionen ausgeben, damit sie als Eingabe verwendet wird.

Auch wenn Du in der Metadaten-Datei Deiner Aktion keine Ausgabe deklarierst, kannst Du dennoch Ausgaben festlegen und in einem Workflow verwenden. Weitere Informationen zum Festlegen von Ausgaben in einer Aktion findest Du unter "Workflow-Befehle für GitHub Actions."

Beispiel

outputs:
  sum: # ID der Ausgabe
    description: 'Die Summe der Eingaben'

outputs.<output_id>

Erforderlich Ein Kennzeichner, der die Ausgabe identifiziert, als String. Der Wert von <output_id> ist eine Übersicht zu den Metadaten der Ausgabe. Die <output_id> muss im Objekt outputs als ein eindeutiger Kennzeichner vorhanden sein. Die <output_id> muss mit einem Buchstaben oder _ beginnen und darf nur alphanumerische Zeichen, - oder _ enthalten.

outputs.<output_id>.description

Erforderlich Eine Beschreibung des Ausgabeparameters als String.

-Ausgaben für Aktionen mit zusammengesetzten Ausführungsschritten

Optional outputs use the same parameters as outputs.<output_id> and outputs.<output_id>.description (see "outputs for GitHub Actions"), but also includes the value token.

Beispiel

Outputs:
  Zufallszahl: 
    Beschreibung: "Zufallszahl"
    Wert:{{ steps.random-number-generator.outputs.random-id }}
läuft:
  mit: "composite"
  Schritten: 
    - id: zuzufälliger Zahlengenerator
      ausführen: echo "::set-output name=random-id::'(echo $RANDOM)"
      Shell: bash

outputs.<output_id.value>

Erforderliche Der Wert, dem der Ausgabeparameter zugeordnet wird. Sie können dies auf eine Zeichenfolge oder einen Ausdruck mit Kontext festlegen. Sie können z. B. die Schritte Kontext verwenden, um den Wert einer Ausgabe auf den Ausgabewert eines Schritts festzulegen.

For more information on how to use context and expression syntax, see "Context and expression syntax for GitHub Actions".

runs für JavaScript-Aktionen

Erforderlich Konfiguriert den Pfad zum Code der Aktion und zu der Anwendung, die den Code ausführen soll.

Beispiel für die Verwendung von Node.js

runs:
  using: 'node12'
  main: 'main.js'

runs.using

Erforderlich Die Anwendung, welche den in main angegebenen Code ausführen soll.

runs.main

Erforderlich Die Datei, die den Code Deiner Aktion enthält. Die in using angegebene Anwendung führt diese Datei aus.

pre

Optional Erlaubt es Dir, ein Skript am Anfang eines Jobs auszuführen, bevor die main:-Aktion startet. Du kannst pre: zum Beispiel verwenden, um mit einem Setup-Skript die Voraussetzungen zu schaffen. Die mit der Syntax using angegebene Anwendung wird diese Datei ausführen. Die pre:-Aktion wird normalerweise immer ausgeführt, aber Du kannst dies mit pre-if ändern.

In diesem Beispiel führt die pre:-Aktion ein Skript namens setup.js aus:

runs:
  using: 'node12'
  pre: 'setup.js'
  main: 'index.js'
  post: 'cleanup.js'

pre-if

Optional Erlaubt Dir, Bedingungen für die Ausführung der pre:-Aktion festzulegen. Die pre:-Aktion läuft nur, wenn die Bedingungen in pre-if erfüllt sind. Wenn pre-if nicht definiert ist, gilt always() als Standardwert. Beachte, dass der step-Kontext nicht verfügbar ist, da noch keine Schritte ausgeführt wurden.

In diesem Beispiel läuft cleanup.js nur auf Linux-basierten Runnern:

  pre: 'cleanup.js'
  pre-if: 'runner.os == linux'

Beitrag

Optional Erlaubt es Dir, ein Skript am Ende eines Jobs auszuführen, sobald die main:-Aktion abgeschlossen ist. Zum Beispiel kannst Du post: verwenden, um bestimmte Prozesse zu beenden oder unnötige Dateien zu entfernen. Die mit der Syntax using angegebene Anwendung wird diese Datei ausführen.

In diesem Beispiel führt die post:-Aktion ein Skript namens cleanup.js aus:

runs:
  using: 'node12'
  main: 'index.js'
  post: 'cleanup.js'

Die post:-Aktion wird normalerweise immer ausgeführt, aber Du kannst dies mit post-if ändern.

post-if

Optional Erlaubt Dir, Bedingungen für die Ausführung der post:-Aktion festzulegen. Die post:-Aktion läuft nur, wenn die Bedingungen in post-if erfüllt sind. Wenn post-if nicht definiert ist, gilt always() als Standardwert.

In diesem Beispiel läuft cleanup.js nur auf Linux-basierten Runnern:

  post: 'cleanup.js'
  post-if: 'runner.os == linux'

führt für Aktionen für zusammengesetzte Ausführungsschritte aus

Erforderliche Konfiguriert den Pfad zur zusammengesetzten Aktion und die Anwendung, die zum Ausführen des Codes verwendet wird.

runs.using

Erforderliche Um eine Aktion für zusammengesetzte Ausführungsschritte zu verwenden, legen Sie diese auf "zusammengesetzte"fest.

runs.steps

Erforderliche Die Ausführungsschritte, die Sie in dieser Aktion ausführen möchten.

runs.steps.run

Erforderliche Der Befehl, den Sie ausführen möchten. Dies kann inline oder ein Skript in Ihrem Aktions-Repository sein:

läuft:
  mit: "composite"
  Schritte: 
    - ausführen:/test/script.sh
      Shell: bash

Alternativ können Sie $GITHUB_ACTION_PATHverwenden:

läuft:
  verwenden: "composite"
  Schritte: 
    - ausführen: $GITHUB_ACTION_PATH/script.sh
      Shell: bash

Weitere Informationen finden Sie unter "github context".

runs.steps.shell

Erforderliche Die Shell, in der Sie den Befehl ausführen möchten. Sie können eine der hier aufgeführten Shells verwenden.

runs.steps.name

Optionaler Der Name des zusammengesetzten Ausführungsschritts.

runs.steps.id

Optionaler Ein eindeutiger Bezeichner für den Schritt. Anhand der id können Sie in Kontexten auf den Schritt verweisen. Weitere Informationen findest Du unter "Kontext- und Ausdrucks-Syntax für GitHub Actions".

runs.steps.env

Optionale Legt eine Zuordnung von Umgebungsvariablen nur für diesen Schritt fest. If you want to modify the environment variable stored in the workflow, use echo "{name}={value}" >> $GITHUB_ENV in a composite run step.

runs.steps.working-directory

Optionale Gibt das Arbeitsverzeichnis an, in dem der Befehl ausgeführt wird.

runs für Docker-Aktionen

Erforderlich Konfiguriert das Image, welches für die Docker-Aktion verwendet wird.

Beispiel für die Nutzung eines Dockerfiles in Deinem Repository

runs: 
  using: 'docker'
  image: 'Dockerfile'

Beispiel zur Nutzung des öffentlichen Docker-Registry-Containers

läuft: 
  mit: 'docker'
  Image: 'docker://debian:stretch-slim'

runs.using

Erforderlich Du musst diesen Wert auf 'docker' setzen.

pre-entrypoint

Optional Erlaubt Dir, ein Skript auszuführen, bevor die Aktion entrypoint beginnt. Du kannst pre-entrypoint: zum Beispiel verwenden, um mit einem Setup-Skript die Voraussetzungen zu schaffen. GitHub Actions verwendet docker run, um diese Aktion zu starten, und führt das Skript in einem neuen Container aus, der das gleiche Basis-Image verwendet. Das bedeutet, dass sich der Laufzeitstatus vom Container des Haupt-entrypoint unterscheidet, und alle benötigten Zustände müssen entweder im Arbeitsbereich, HOME, oder als STATE_-Variable verwendet werden. Die pre-entrypoint:-Aktion wird normalerweise immer ausgeführt, aber Du kannst dies mit pre-if ändern.

Die mit der Syntax using angegebene Anwendung wird diese Datei ausführen.

In diesem Beispiel führt die pre-entrypoint:-Aktion ein Skript namens setup.sh aus:

runs:
  using: 'docker'
  image: 'Dockerfile'
  args:
  - 'bzz'
  pre-entrypoint: 'setup.sh'
  entrypoint: 'main.sh'

runs.image

Erforderlich Das Docker-Image, das als Container zum Ausführen der Aktion verwendet werden soll. Der Wert kann der Name des Docker-Basis-Images sein, eine lokale Dockerdatei in Deinem Repository, oder ein öffentliches Image im Docker-Hub oder in einer anderen Registry. Um eine lokale Dockerdatei innerhalb Deines Repositorys zu referenzieren, gibst Du einen Pfad relativ zur Metadaten-Datei Deiner Aktion an. Die Docker-Anwendung wird diese Datei ausführen.

runs.env

Optional Gibt eine Schlüssel-Wert-Zuordnung von Umgebungsvariablen an, die in der Containerumgebung festgelegt werden sollen.

runs.entrypoint

Optional Überschreibt den ENTRYPOINT des Dockers in der Dockerdateioder setzt ihn, falls nicht bereits angegeben. Verwende Entrypoint, wenn die Dockerdatei gibt keinen Entrypoint angibt, oder wenn Du die Anweisung Entrypoint überschreiben willst. Wenn Du Entrypoint weglässt, werden jene Befehle ausgeführt, welche Du in der Anweisung Entrypoint des Dockers angibst. Für die Docker-Anweisung ENTRYPOINT gibt es sowohl eine shell-Form als auch eine exec-Form. Die Docker-Dokumentation für ENTRYPOINT empfiehlt die exec-Form der ENTRYPOINT-Anweisung.

Weitere Informationen dazu, wie die Entrypoint ausgeführt wird, findest Du unter "Dockerdatei-Unterstützung für GitHub Actions."

post-entrypoint

Optional Erlaubt Dir, ein Aufräumskript auszuführen, sobald die Aktion runs.entrypoint abgeschlossen ist. GitHub Actions verwendet docker run um diese Aktion zu starten. Da GitHub Actions das Skript in einem neuen Container mit dem glaichen Basis-Image ausführt, unterscheidet sich der Laufzeitstatus vom Container des Haupt-entrypoint. Du kannst auf jeden benötigten Zustand, entweder im Arbeitsbereich, HOME, oder als STATE_-Variable zugreifen. Die post-entrypoint:-Aktion wird normalerweise immer ausgeführt, aber Du kannst dies mit post-if ändern.

runs:
  using: 'docker'
  image: 'Dockerfile'
  args:
  - 'bzz'
  entrypoint: 'main.sh'
  post-entrypoint: 'cleanup.sh'

runs.args

Optional Ein Array von Strings, welche die Eingaben für einen Docker-Container definieren. Eingaben können hartcodierte Strings enthalten. Beim Start des Containers übergibt GitHub die args-Anweisung an den ENTRYPOINT des Containers.

Die args-Anweisungen werden anstelle der CMD-Anweisung in einem Dockerfile verwendet. Falls Sie CMD in Ihrem Dockerfile verwenden, sollten Sie sich an die nach Präferenz angeordneten Richtlinien halten:

1. Dokumentiere die erforderlichen Argumente in der README der Aktion und lasse sie in der CMD-Anweisung weg.
2. Verwenden Sie Standardwerte, die die Verwendung der Aktion ohne Angabe von args erlauben.
3. Wenn die Aktion ein --help Flag oder etwas ähnliches verfügbar macht, verwende dieses, um Deine Aktion selbstdokumentierend zu machen.

Wenn Du Umgebungsvariablen an eine Aktion übergeben musst, stelle sicher, dass Deine Aktion eine Kommando-Shell ausführt, damit die Variablen ausgewertet werden. Wenn z. B. Dein Entrypoint-Attribut auf "sh -c" gesetzt ist, werden die args an eine Kommando-Shell übergeben. Oder wenn Deine Dockerdatei einen Entrypoint verwendet, um denselben Befehl ("sh -c") auszuführen, werden die args ebenfalls an eine Kommando-Shell übergeben.

Weitere Informationen zur Verwendung der Anweisung CMD mit GitHub Actionsfindest Du unter "Dockerdate-Unterstützung für GitHub Actions."

Beispiel

runs:
  using: 'docker'
  image: 'Dockerfile'
  args:
    - ${{ inputs.greeting }}
    - 'foo'
    - 'bar'

branding

Du kannst mit einer Farbe und Feder ein Badge zu erstellen, um Deine Aktion zu personalisieren und von anderen zu unterscheiden. Badges werden neben Deinem Aktionsnamen in GitHub Marketplace angezeigt.

Beispiel

branding:
  icon: 'award'  
  color: 'green'

branding.color

Die Hintergrundfarbe des Badges. Kann eine der folgenden sein: white, yellow, blue, green, orange, red, purple oder gray-dark.

branding.icon

Der Name des zu verwendenden Federsymbols.