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

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.

Voraussetzungen

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

• Variablen
• Informationen zu von GitHub gehostete Runnern

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

1. Erstelle ein neues Repository auf deine GitHub Enterprise Server-Instanz. Du kannst einen beliebigen Repository-Namen auswählen oder wie in diesem Beispiel „hello-world-docker-action“ verwenden. Weitere Informationen findest du unter Ein neues Repository erstellen.

2. Klone dein Repository auf deinen Computer. Weitere Informationen findest du unter Ein Repository klonen.

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

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

# 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 Workflow commands for GitHub Actions (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 Setting exit codes for actions (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

# 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 benutzerdefinierten Aktionen.

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, kannst du bestimmen, wer auf sie zugreifen darf. Weitere Informationen findest du unter Verwalten von GitHub Actions-Einstellungen für ein Repository.
• Öffentliche Aktionen können von Workflows in jedem beliebigen Repository verwendet werden.

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

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

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@v3
      - 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.

Wähle Hello world action step aus. Im Protokoll sollten „Hello Mona the Octocat“ oder der von dir für die who-to-greet-Eingabe verwendete Name ausgegeben werden. Wähle Ausgabezeit abrufen aus, um den Zeitstempel anzuzeigen.