Skip to main content
We publish frequent updates to our documentation, and translation of this page may still be in progress. For the most current information, please visit the English documentation.

Creating a Docker container action (Erstellen einer Docker-Containeraktion)

In diesem Leitfaden werden die mindestens erforderlichen Schritte zum Erstellen einer Docker-Containeraktion beschrieben.

Hinweis: GitHub-gehostete Runner werden auf GitHub Enterprise Server derzeit nicht unterstützt. Weitere Informationen zur geplanten zukünftigen Unterstützung findest Du in der GitHub public roadmap.

Einführung

In dieser Anleitung erfährst du mehr über die grundlegenden Komponenten, die benötigt werden, um eine paketierte Docker-Containeraktion zu erstellen und zu verwenden. Diese Anleitung fokussiert jene Komponenten, welche zum Paketieren der Aktion benötigt werden. Daher hat der Aktions-Code nur minimale Funktionalität. Die Aktion schreibt „Hello World“ in die Logs oder "Hello [who-to-greet]" wenn du einen benutzerdefinierten Namen angibst.

Nach dem Abschluss dieses Projekts wirst du verstehen, wie du deine eigene Docker-Containeraktion erstellen und sie in einem Workflow testen kannst.

Selbst gehostete Läufer müssen ein Linux-Betriebssystem verwenden und Docker installiert haben, um Docker Containeraktionen auszuführen. Weitere Informationen zu den Anforderungen selbstgehosteter Runner findest du unter Informationen zu selbstgehosteten Runnern.

Warnung: Beim Erstellen von Workflows und Aktionen solltest du immer überprüfen, ob dein Code gegebenenfalls nicht vertrauenswürdige Eingaben von Angreifern ausführen kann. Bestimmte Kontexte sollten als nicht vertrauenswürdige Eingaben behandelt werden, da ein Angreifer seine eigenen schädlichen Inhalte einfügen könnte. Weitere Informationen findest du unter „Grundlegendes zum Risiko von Skript-Einfügungen".

Voraussetzungen

Es wird dir vielleicht helfen, GitHub Actions-Umgebungsvariablen und das Docker-Containerdateisystem grundlegend zu verstehen:

Bevor du beginnst, musst du ein GitHub-Repository erstellen.

  1. Erstelle ein neues Repository auf your GitHub Enterprise Server instance. Du kannst einen beliebigen Repository-Namen auswählen oder wie in diesem Beispiel „hello-world-docker-action“ verwenden. Weitere Informationen findest du unter Erstellen eines neuen Repositorys.

  2. Klone dein Repository auf deinen Computer. Weitere Informationen findest du unter Klonen eines Repositorys.

  3. Gehe in deinem Terminal zum Verzeichnisse deines neuen Repositorys.

    Shell
    cd hello-world-docker-action

Eine Docker-Datei erstellen

Erstelle in deinem neuen hello-world-docker-action-Verzeichnis eine neue Dockerfile-Datei. Stelle sicher, dass dein Dateiname richtig großgeschrieben ist, wenn Probleme auftreten. Verwende ein großes D, aber kein großes f. Weitere Informationen findest du unter Dockerfile-Unterstützung für GitHub Actions.

Dockerfile

Dockerfile
# Container image that runs your code
FROM alpine:3.10

# Copies your code file from your action repository to the filesystem path `/` of the container
COPY entrypoint.sh /entrypoint.sh

# Code file to execute when the docker container starts up (`entrypoint.sh`)
ENTRYPOINT ["/entrypoint.sh"]

Eine Datei für die Metadaten der Aktion erstellen

Erstelle eine neue action.yml-Datei im oben erstellten hello-world-docker-action-Verzeichnis. Weitere Informationen findest du unter Metadatensyntax für GitHub Actions.

action.yml

YAML
# action.yml
name: 'Hello World'
description: 'Greet someone and record the time'
inputs:
  who-to-greet:  # id of input
    description: 'Who to greet'
    required: true
    default: 'World'
outputs:
  time: # id of output
    description: 'The time we greeted you'
runs:
  using: 'docker'
  image: 'Dockerfile'
  args:
    - ${{ inputs.who-to-greet }}

Diese Metadaten definieren einen who-to-greet-Eingabe- und einen time-Ausgabeparameter. Um Eingaben an den Docker-Container zu übergeben, solltest du die Eingabe mithilfe von inputs deklarieren und mithilfe des Schlüsselworts args übergeben. Alles, was in args enthalten ist, wird an den Container übergeben, doch für eine bessere Auffindbarkeit für Benutzer*innen deiner Aktion wird das Verwenden von Eingaben empfohlen.

GitHub erstellt basierend auf deinem Dockerfile ein Image und führt mithilfe dieses Images Befehle in einem neuen Container aus.

Aktions-Code schreiben

Du kannst ein beliebiges Basis-Docker-Image und folglich auch eine beliebige Sprache für deine Aktion auswählen. Im folgenden Shellskriptbeispiel wird die Eingabevariable who-to-greet verwendet, um in der Protokolldatei „Hello [who-to-greet]“ auszugeben.

Als Nächstes ruft das Skript die aktuelle Zeit ab und legt sie als eine Ausgabevariable fest, die von später in einem Auftrag ausgeführten Aktionen verwendet werden kann. Damit GitHub die Ausgabevariablen erkennen kann, musst du sie einen Workflowbefehl mit einer bestimmten Syntax verwenden: echo "::set-output name=<output name>::<value>". Weitere Informationen findest du unter Workflowbefehle für GitHub Actions.

  1. Erstelle im hello-world-docker-action-Verzeichnis eine neue entrypoint.sh-Datei.

  2. Füge deiner entrypoint.sh-Datei den folgenden Code hinzu:

    entrypoint.sh

    Shell
    #!/bin/sh -l
    
    echo "Hello $1"
    time=$(date)
    echo "::set-output name=time::$time"

    Wenn entrypoint.sh ohne Fehler ausgeführt wird, wird der Status der Aktion auf success festgelegt. Du kannst auch explizit Exitcodes im Code deiner Aktion festlegen, um einen Status der Aktion anzugeben. Weitere Informationen findest du unter Festlegen von Exitcodes für Aktionen.

  3. Mache deine Datei entrypoint.sh ausführbar. Git bietet eine Möglichkeit, den Berechtigungsmodus einer Datei explizit zu ändern, damit er nicht bei jedem Klon-/Forkvorgang zurückgesetzt wird.

    Shell
    $ git add entrypoint.sh
    $ git update-index --chmod=+x entrypoint.sh
  4. Um den Berechtigungsmodus der Datei im Git-Index zu überprüfen, kannst du optional folgenden Befehl ausführen.

    Shell
    $ git ls-files --stage entrypoint.sh

    Eine Ausgabe wie 100755 e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 0 entrypoint.sh bedeutet, dass die Datei die Berechtigung „Ausführbar“ hat. In diesem Beispiel gibt 755 die Berechtigung „Ausführbar“ an.

Eine README erstellen

Du kannst eine README-Datei erstellen, um Person zu zeigen, wie sie deine Aktion verwenden sollen. Ein README ist sehr hilfreich, wenn Du planst, Deine Aktion öffentlich bereitzustellen, aber es ist auch eine großartige Möglichkeit, Dich oder Dein Team daran zu erinnern, wie die Aktion zu verwenden ist.

Erstelle in deinem hello-world-docker-action-Verzeichnis eine README.md-Datei, mit der die folgenden Informationen angegeben werden:

  • Eine ausführliche Beschreibung, wozu die Aktion dient
  • Erforderliche Eingabe- und Ausgabeargumente
  • Optionale Eingabe- und Ausgabeargumente
  • Geheimnisse, die von der Aktion verwendet werden
  • Umgebungsvariablen, die von der Aktion verwendet werden
  • Ein Beispiel für die Verwendung deiner Aktion in einem Workflow

README.md

markdown
# Hello world docker action

This action prints "Hello World" or "Hello" + the name of a person to greet to the log.

## Inputs

## `who-to-greet`

**Required** The name of the person to greet. Default `"World"`.

## Outputs

## `time`

The time we greeted you.

## Example usage

uses: actions/hello-world-docker-action@v1
with:
  who-to-greet: 'Mona the Octocat'

Committen, Markieren und Pushen der Aktion zu GitHub Enterprise Server

Committe von deinem Terminal aus deine action.yml-, entrypoint.sh-, Dockerfile- und README.md-Dateien.

Es hat sich bewährt, auch ein Versions-Tag für Releases deiner Aktion hinzuzufügen. Weitere Informationen zur Versionsverwaltung deiner Aktion findest du unter Informationen zu Aktionen.

Shell
git add action.yml entrypoint.sh Dockerfile README.md
git commit -m "My first action is ready"
git tag -a -m "My first action release" v1
git push --follow-tags

Deine Aktion in einem Workflow testen

Nun bist du bereit, deine Aktion in einem Workflow zu testen.

  • Wenn sich eine Aktion in einem privaten Repository befindet, kann die Aktion nur in Workflows im selben Repository verwendet werden. - Wenn sich eine Aktion in einem internen Repository befindet, kann die Aktion nur in Workflows im selben Repository verwendet werden.
  • Öffentliche Aktionen können von Workflows in jedem beliebigen Repository verwendet werden.

Hinweis: GitHub Actions auf your GitHub Enterprise Server instance haben möglicherweise nur eingeschränkten Zugriff auf Aktionen auf GitHub.com oder im GitHub Marketplace. Weitere Informationen findest du unter Verwalten des Zugriffs auf Aktionen aus GitHub.com. Zudem kannst du deinen GitHub Enterprise-Websiteadministratorin kontaktieren.

Beispiel mit einer öffentlichen Aktion

Der folgende Workflowcode verwendet die abgeschlossene hello world-Aktion im öffentlichen actions/hello-world-docker-action-Repository. Kopiere den folgenden Workflow-Beispielcode in eine .github/workflows/main.yml-Datei, ersetze jedoch actions/hello-world-docker-action durch dein Repository und den Aktionsnamen. Du kannst auch die who-to-greet-Eingabe durch deinen Namen ersetzen.

.github/workflows/main.yml

YAML
on: [push]

jobs:
  hello_world_job:
    runs-on: ubuntu-latest
    name: A job to say hello
    steps:
      - name: Hello world action step
        id: hello
        uses: actions/hello-world-docker-action@v1
        with:
          who-to-greet: 'Mona the Octocat'
      # Use the output from the `hello` step
      - name: Get the output time
        run: echo "The time was ${{ steps.hello.outputs.time }}"

Beispiel mit einer privaten Aktion

Kopiere den folgenden Workflow-Beispielcode in eine .github/workflows/main.yml-Datei im Repository deiner Aktion. Du kannst auch die who-to-greet-Eingabe durch deinen Namen ersetzen.

.github/workflows/main.yml

YAML
on: [push]

jobs:
  hello_world_job:
    runs-on: ubuntu-latest
    name: A job to say hello
    steps:
      # To use this repository's private action,
      # you must check out the repository
      - name: Checkout
        uses: actions/checkout@v2
      - name: Hello world action step
        uses: ./ # Uses an action in the root directory
        id: hello
        with:
          who-to-greet: 'Mona the Octocat'
      # Use the output from the `hello` step
      - name: Get the output time
        run: echo "The time was ${{ steps.hello.outputs.time }}"

Klicke in deinem Repository auf die Registerkarte Aktionen, und wähle die neueste Workflowausführung aus. Klicke unter Aufträge oder im Visualisierungsdiagramm auf A job to say hello. Im Protokoll sollten „Hello Mona the Octocat“ oder der von Ihnen für die who-to-greet-Eingabe verwendete Name und der Zeitstempel ausgegeben werden.

Ein Screenshot zur Verwendung deiner Aktion in einem Workflow