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 YAML für Dich Neuland ist, lies den Artikel „YAML in fünf Minuten lernen“.

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 The name of the action's author.

Beschreibung

Erforderlich Eine kurze Beschreibung der Aktion.

inputs

Optional Input parameters allow you to specify data that the action expects to use during runtime. GitHub speichert Eingabeparameter als Umgebungsvariablen. Eingabe-IDs in Großbuchstaben werden während der Laufzeit in Kleinbuchstaben umgewandelt. Du solltest Eingabe-IDs in Kleinbuchstaben verwenden.

Beispiel

In diesem Beispiel werden zwei Eingaben konfiguriert: „numOctocats“ und „octocatEyeColor“. Die Eingabe „numOctocats“ ist nicht erforderlich und hat standardmäßig den Wert ‚1‘. Die Eingabe „octocatEyeColor“ ist erforderlich und hat keinen Standardwert. Workflow-Dateien, die diese Aktion nutzen, müssen das Schlüsselwort 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

When you specify an input in a workflow file or use a default input value, GitHub creates an environment variable for the input with the name INPUT_<VARIABLE_NAME>. Der Name der aus dem Eingabenamen erstellten Umgebungsvariablen wird in Großbuchstaben umgewandelt und Leerzeichen werden durch das Zeichen _ ersetzt.

If the action is written using a composite, then it will not automatically get INPUT_<VARIABLE_NAME>. If the conversion doesn't occur, you can change these inputs manually.

To access the environment variable in a Docker container action, you must pass the input using the args keyword in the action metadata file. For more information about the action metadata file for Docker container actions, see "Creating a Docker container action."

For example, if a workflow defined the numOctocats and octocatEyeColor inputs, the action code could read the values of the inputs using the INPUT_NUMOCTOCATS and INPUT_OCTOCATEYECOLOR environment variables.

inputs.<input_id>

Erforderlich Ein Kennzeichner, der die Eingabe identifiziert, als string. The value of <input_id> is a map of the input's metadata. 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 A string representing the default value. Der Standardwert wird verwendet, wenn ein Eingabeparameter in einer Workflow-Datei nicht angegeben ist.

inputs.<input_id>.deprecationMessage

Optional If the input parameter is used, this string is logged as a warning message. You can use this warning to notify users that the input is deprecated and mention any alternatives.

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 dort 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.

outputs for composite actions

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:
  random-number:
    description: "Random number"
    value: ${{ steps.random-number-generator.outputs.random-id }}
runs:
  using: "composite"
  steps:
    - id: random-number-generator
      run: echo "::set-output name=random-id::$(echo $RANDOM)"
      shell: bash

outputs.<output_id>.value

Required The value that the output parameter will be mapped to. You can set this to a string or an expression with context. For example, you can use the steps context to set the value of an output to the output value of a step.

For more information on how to use context syntax, see "Contexts."

runs for JavaScript actions

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'

runs for composite actions

Required Configures the path to the composite action, and the application used to execute the code.

runs.using

Required To use a composite action, set this to "composite".

runs.steps

Required The steps that you plan to run in this action.

runs.steps[*].run

Required The command you want to run. This can be inline or a script in your action repository:

runs:
  using: "composite"
  steps:
    - run: ${{ github.action_path }}/test/script.sh
      shell: bash

Alternatively, you can use $GITHUB_ACTION_PATH:

runs:
  using: "composite"
  steps:
    - run: $GITHUB_ACTION_PATH/script.sh
      shell: bash

For more information, see "github context".

runs.steps[*].shell

Required The shell where you want to run the command. You can use any of the shells listed here. Required if run is set.

runs.steps[*].name

Optional The name of the composite step.

runs.steps[*].id

Optional A unique identifier for the step. Anhand der id können Sie in Kontexten auf den Schritt verweisen. Weitere Informationen finden Sie unter „Kontexte“.

runs.steps[*].env

Optional Sets a map of environment variables for only that step. If you want to modify the environment variable stored in the workflow, use echo "::set-env name={name}::{value}" in a composite step.

runs.steps[*].working-directory

Optional Specifies the working directory where the command is run.

runs for Docker actions

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

runs:
  using: '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. To reference a Dockerfile local to your repository, the file must be named Dockerfile and you must use a path relative to your action metadata file. 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.