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 Sicherheitshärtung für GitHub Actions.
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.
-
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.
-
Klone dein Repository auf deinen Computer. Weitere Informationen findest du unter Ein Repository klonen.
-
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).
-
Erstelle im
hello-world-docker-action
-Verzeichnis eine neueentrypoint.sh
-Datei. -
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 aufsuccess
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). -
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
-
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 gibt755
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.
Hinweis: GitHub Actions auf deine GitHub Enterprise Server-Instanz 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 in GitHub.com, oder wende dich an dendie GitHub Enterprise-Websiteadministratorin.
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.