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 Selbstgehosteten Runnern.

Warnung

Bei der Erstellung von Workflows und Aktionen sollten Sie immer bedenken, ob Ihr Code nicht vertrauenswürdige Eingaben von möglichen Eindringlingen ausführen könnte. Bestimmte Kontexte sollten als nicht vertrauenswürdige Eingaben behandelt werden, da ein Angreifer seine eigenen schädlichen Inhalte einfügen könnte. Weitere Informationen finden Sie unter Referenz zur sicheren Verwendung.

Voraussetzungen

Sie müssen ein Repository für GitHub erstellen und auf Ihrer Workstation klonen. Weitere Informationen findest du unter Ein neues Repository erstellen und Ein Repository klonen.
Wenn Ihr RepositoryGit LFS verwendet, müssen Sie die Objekte in Archive Ihres Repositorys einschließen. Weitere Informationen finden Sie unter Verwalten von Git LFS-Objekten in Archiven deines Repositorys.
Es wird dir vielleicht helfen, GitHub Actions-Umgebungsvariablen und das Docker-Containerdateisystem grundlegend zu verstehen: Weitere Informationen findest du unter Speichern von Informationen in Variablen und Von GitHub gehostete Runner.

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 finden Sie unter Dockerfile Unterstützung für GitHub Aktionen.

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"]

# 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 finden Sie unter Referenz zur Metadatensyntax.

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 }}

# 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, müssen Sie sie in die $GITHUB_OUTPUT-Umgebungsdatei schreiben: echo "<output name>=<value>" >> $GITHUB_OUTPUT. Weitere Informationen finden Sie unter Workflow commands for GitHub Actions (Workflowbefehle für GitHub Actions).

Erstelle im hello-world-docker-action-Verzeichnis eine neue entrypoint.sh-Datei.
Füge deiner entrypoint.sh-Datei den folgenden Code hinzu:

entrypoint.sh
Shell
```
#!/bin/sh -l

echo "Hello $1"
time=$(date)
echo "time=$time" >> $GITHUB_OUTPUT
```
```
#!/bin/sh -l

echo "Hello $1"
time=$(date)
echo "time=$time" >> $GITHUB_OUTPUT
```
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 finden Sie unter Setting exit codes for actions (Festlegen von Exitcodes für Aktionen).
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
```
```
git add entrypoint.sh
git update-index --chmod=+x entrypoint.sh
```
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
```
```
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@v2
with:
  who-to-greet: 'Mona the Octocat'

# 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@v2
with:
  who-to-greet: 'Mona the Octocat'

Committen, Taggen und Pushen deiner Aktion

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.

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

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, kannst du bestimmen, wer auf sie zugreifen darf. Weitere Informationen finden Sie unter Verwalten von GitHub Actions-Einstellungen für ein Repository.
Wenn sich eine Aktion in einem internen Repository befindet, kannst du steuern, wer darauf 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. Öffentliche Aktionen können auch dann verwendet werden, wenn sie nicht auf dem GitHub Marketplace veröffentlicht sind. Weitere Informationen finden Sie unter Aktionen auf dem GitHub-Marktplatz veröffentlichen.

.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@v2
        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 }}"

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@v2
        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. Diese private Aktion kann nicht auf dem GitHub Marketplace veröffentlicht und kann nur in diesem Repository verwendet werden.

.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@v5
      - 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 }}"

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@v5
      - 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. Um den Zeitstempel anzuzeigen, klicke auf Ausgabezeit abrufen.

Zugreifen auf Dateien, die von einer Containeraktion erstellt wurden

Wenn eine Containeraktion ausgeführt wird, wird automatisch das Standardarbeitsverzeichnis (GITHUB_WORKSPACE) auf dem Runner mit dem /github/workspace Verzeichnis im Container zugeordnet. Alle Dateien, die diesem Verzeichnis im Container hinzugefügt wurden, sind für alle nachfolgenden Schritte im selben Auftrag verfügbar. Wenn Sie beispielsweise über eine Containeraktion verfügen, die Ihr Projekt erstellt, und Sie die Buildausgabe als Artefakt hochladen möchten, können Sie die folgenden Schritte ausführen.

workflow.yml

YAML

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v5

      # Output build artifacts to /github/workspace on the container.
      - name: Containerized Build
        uses: ./.github/actions/my-container-action

      - name: Upload Build Artifacts
        uses: actions/upload-artifact@v4
        with:
          name: workspace_artifacts
          path: ${{ github.workspace }}

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v5

      # Output build artifacts to /github/workspace on the container.
      - name: Containerized Build
        uses: ./.github/actions/my-container-action

      - name: Upload Build Artifacts
        uses: actions/upload-artifact@v4
        with:
          name: workspace_artifacts
          path: ${{ github.workspace }}

Weitere Informationen zum Hochladen der Buildausgabe als Artefakt findest du unter Speichern und Freigeben von Daten mit Workflowartefakten.

Beispielaktionen für Docker-Container unter GitHub.com

Beispielaktionen für Docker-Container findest du unter GitHub.com.

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

In diesem Artikel