Eine Docker-Container-Aktion erstellen

Einführung

In dieser Anleitung erfährst Du mehr über die grundlegenden Komponenten, die benötigt werden, um eine paketierte Docker-Container-Aktion 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 von selbst-gehosteten Läufern findest Du unter"Über selbst-gehostete Läufer".

Vorrausetzungen

Es wir Dir vielleicht helfen, GitHub Actions Umgebungsvariablen und das Docker-Container-Dateisystem grundlegend zu verstehen:

• "Umgebungsvariablen verwenden"

• "Virtuelle Umgebungen für GitHub"

Before you begin, you'll need to create a GitHub repository.

1. Erstellen Sie 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 finden Sie unter „Neues Repository erstellen“.

2. Clone Dein Repository auf Deinen Computer. Weitere Informationen findest Du unter „Ein Repository clonen“.

3. Gehe in Deinem Terminal zum Verzeichnisse Deines neuen Repositorys.

   Shell

   cd hello-world-docker-action

Eine Docker-Datei erstellen

Erstelle im neuen Verzeichnis hello-world-docker-action eine neue Dockerfile-Datei. For more information, see "Dockerfile support for GitHub Actions."

Dockerfile

# Container-Image, das Deinen Code ausführt
FROM alpine:3.10

# Kopiert die Codedatei aus Deinem Aktions-Repository in den Dateisystempfad `/` des Containers
COPY entrypoint.sh /entrypoint.sh

# Codedatei, die beim Start des Docker-Containers ausgeführt werden soll (`entrypoint.sh`)
ENTRYPOINT ["/entrypoint.sh"]

Eine Datei für die Metadaten der Aktion erstellen

Erstelle eine neue action.yml-Datei im oben von Dir erstellten Verzeichnis hello-world-docker-action. Weitere Informationen findest Du unter „Metadaten-Syntax für GitHub Actions“.

action.yml

# action.yml
name: 'Hello World'
description: 'Greet someone and record the time'
inputs:
  who-to-greet:  # Eingabe-ID
    description: 'Who to greet'
    required: true
    default: 'World'
outputs:
  time: # Ausgabe-ID
    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 weiterzugeben, musst Du die Eingabe mit inputs deklarieren und die Eingabe im Schlüsselwortargs weitergeben.

GitHub erstellt basierend auf Ihrem 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 Shellskript-Beispiel 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 Ausgabevariablen erkennen kann, musst Du einen Workflow-Befehl in einer bestimmten Syntax verwenden: echo "::set-output name=<output name>::<value>". Weitere Informationen findest Du unter „Workflow-Befehle für GitHub Actions“.

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

2. Füge Deiner Datei entrypoint.sh 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 durchläuft, wird der Status der Aktion auf success (erfolgreich) festgelegt. Du kannst auch explizit Exit-Codes im Code Deiner Aktion festlegen, um einen Status der Aktion anzugeben. Weitere Informationen findest Du unter "Exit Codes für Aktionen setzen."

3. Make your entrypoint.sh file executable by running the following command on your system.

   Shell

   $ chmod +x entrypoint.sh

Eine README erstellen

Sie können eine README-Datei erstellen, um Person dahingehend zu informieren, wie sie Ihre Aktion verwenden sollen. Eine README ist am hilfreichsten, wenn Sie vorhaben, Ihre Aktion öffentlich freizugeben. Zudem eignet sie sich dafür, Sie oder Ihr Team dahingehend zu erinnern, wie die Aktion verwendet wird.

Erstellen Sie in Ihrem Verzeichnis hello-world-docker-action eine README.md-Datei, welche die folgenden Informationen angibt:

• Eine ausführliche Beschreibung, was die Aktion bewirkt.
• Erforderliche Eingabe- und Ausgabe-Argumente.
• Optionale Eingabe- und Ausgabe-Argumente.
• Geheimnisse, die in der Aktion benutzt werden.
• Umgebungsvariablen, die in der Aktion benutzt werden.
• Ein Beispiel für die Verwendung Deiner Aktion in einem Workflow.

README.md

# Docker-Aktion „Hello world“

Diese Aktion gibt „Hello World“ oder „Hello“ + den Namen einer Person aus, die im Protokoll gegrüßt werden soll.

## Inputs

## `who-to-greet`

**Required** The name of the person to greet. Der Standardwert lautet „World“.

## Outputs

## `time`

The time we greeted you.

## Example usage

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

Commit, tag, and push your action to GitHub Enterprise Server

Committen Sie in Ihrem Terminal Ihre Dateien action.yml, entrypoint.sh, Dockerfile und README.md.

Es hat sich bewährt, auch ein Versions-Tag für Releases Deiner Aktion hinzuzufügen. Weitere Informationen zur Versionierung Deiner Aktion findest Du unter "Informationen zu 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 sind Sie bereit, Ihre Aktion in einem Workflow zu testen. Wenn eine Aktion in einem privaten Repository vorliegt, kann die Aktion nur in Workflows im selben Repository verwendet werden. Öffentliche Aktionen können von Workflows aus jedem Repository verwendet werden.

Beispiel mit einer öffentlichen Aktion

The following workflow code uses the completed hello world action in the public actions/hello-world-docker-action repository. Kopieren Sie den folgenden Workflow-Beispielcode in eine .github/workflows/main.yml-Datei. Ersetzen Sie jedoch actions/hello-world-docker-action durch Ihren Repository- und Aktionsnamen. Darüber hinaus können Sie die Eingabe who-to-greet durch Ihren 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

Kopieren Sie den folgenden Workflow-Beispielcode im Repository Ihrer Aktion in eine .github/workflows/main.yml-Datei. Darüber hinaus können Sie die Eingabe who-to-greet durch Ihren Namen ersetzen.

.github/workflows/main.yml

zu: [push]

Jobs:
  hello_world_job:
    läuft auf: ubuntu-latest
    Name: Ein Job, um Hallo zu sagen
    Schritte:
      . Um die private Aktion dieses Repositorys zu verwenden,
      - Sie müssen das Repository
      - Name: Checkout
        verwendet: Aktionen/checkout@v2
      - Name: Hallo Welt-Aktionsschritt
        verwendet: ./ - Verwendet eine Aktion im Root-Verzeichnis
        ID: hallo
        mit:
          who-to-greet: 'Mona the Octocat'
      . Verwenden Sie die Ausgabe aus dem 'Hallo' Schritt
      - Name: Get the output time
        run:{{ steps.hello.outputs.time }}echo

Klicke in Deinem Repository auf die Registerkarte Actions (Aktionen), und wähle die neueste Workflow-Ausführung aus. You should see "Hello Mona the Octocat" or the name you used for the who-to-greet input and the timestamp printed in the log.