Dockerfile Unterstützung für GitHub Aktionen

Beim Erstellen eines Dockerfile für eine Docker-Containeraktion solltest du wissen, wie bestimmte Docker-Anweisungen mit GitHub Actions und der Metadatendatei einer Aktion interagieren.

In diesem Artikel

Informationen zu Dockerfile-Anweisungen

Eine Dockerfile enthält Anweisungen und Argumente, die den Inhalt und das Startverhalten eines Docker-Containers definieren. Weitere Informationen zu den Anweisungen, die Docker unterstützt, findest du in der Docker-Dokumentation unter Dockerfile-Referenz.

Dockerfile Anweisungen und Overrides (Überschreibungen)

Einige Docker-Anweisungen interagieren mit GitHub-Aktionen, und die Metadaten-Datei einer Aktion kann einige Docker-Anweisungen überschreiben. Vergewissere Dich, dass Dir klar ist, wie dein Dockerfile mit GitHub Actions interagiert, um unerwartetes Verhalten zu verhindern.

USER

Docker-Aktionen müssen vom Standard-Benutzer (root) des Dockers ausgeführt werden. Verwende die USER-Anweisung nicht in deinem Dockerfile, da du dann nicht mehr auf das Verzeichnis GITHUB_WORKSPACE zugreifen kannst. Weitere Informationen findest du in der Docker-Dokumentation unter Speichern von Informationen in Variablen und der USER-Referenz.

FROM

Die erste Anweisung in der Dockerfile muss FROM sein, wodurch ein Docker-Basisimage ausgewählt wird. Weitere Informationen findest du in der Docker-Dokumentation unter FROM-Referenz.

Dies sind einige bewährte Methoden, das FROM-Argument zu nutzen:

  • Es wird empfohlen, offizielle Docker-Images (Abbilder) zu verwenden. Zum Beispiel: python oder ruby.
  • Verwende ein Versions-Tag, falls vorhanden, vorzugsweise mit einer Hauptversion. Verwenden Sie z. B. node:10 statt node:latest.
  • Es wird empfohlen, Docker-Images zu verwenden, die auf dem Debian-Betriebssystem basieren.

WORKDIR

GitHub legt den Pfad zum Arbeitsverzeichnis in der Umgebungsvariablen GITHUB_WORKSPACE fest. Es wird empfohlen, die WORKDIR-Anweisung nicht in deiner Dockerfile zu verwenden. Bevor die Aktion ausgeführt wird, mountet GitHub das Verzeichnis GITHUB_WORKSPACE auf was auch immer sich an dieser Stelle im Docker-Image befindet, und setzt GITHUB_WORKSPACE als Arbeitsverzeichnis. Weitere Informationen findest du in der Docker-Dokumentation unter Speichern von Informationen in Variablen und der WORKDIR-Referenz.

ENTRYPOINT

Wenn du in der Metadatendatei einer Aktion entrypoint definierst, setze ENTRYPOINT, festgelegt in der Dockerfile, außer Kraft. Weitere Informationen finden Sie unter Metadatensyntax für GitHub Actions.

Für die Docker-Anweisung ENTRYPOINT gibt es ein Shellformat und ein Ausführungsformat. In der Docker-Dokumentation zu ENTRYPOINT wird das Ausführungsformat der ENTRYPOINT-Anweisung empfohlen. Weitere Informationen zum Ausführungsformat und Shellformat findest du in der Docker-Dokumentation in der ENTRYPOINT-Referenz.

Verwende WORKDIR nicht, um deinen Einstiegspunkt in deiner Dockerfile-Datei anzugeben. Verwende stattdessen einen absoluten Pfad. Weitere Informationen findest du unter WORKDIR.

Wenn du deinen Container so konfigurierst, dass er das Ausführungsformat der ENTRYPOINT-Anweisung verwendet, wird die in der Metadatendatei der Aktion konfigurierte args nicht in einer Befehlsshell ausgeführt. Wenn die args der Aktion eine Umgebungsvariable enthalten, wird die Variable nicht ersetzt. Wenn du beispielsweise das folgende Ausführungsformat verwendest, wird der in $GITHUB_SHA gespeicherte Wert nicht ausgegeben, sondern stattdessen wird "$GITHUB_SHA" ausgegeben.

ENTRYPOINT ["echo $GITHUB_SHA"]

Wenn du eine Variable ersetzen möchtest, verwende entweder das Shellformat, oder du führst direkt eine Shell aus. Mit dem folgenden Ausführungsformat kannst du zum Beispiel eine Shell ausführen, um den in der Umgebungsvariablen GITHUB_SHA gespeicherten Wert auszugeben.

ENTRYPOINT ["sh", "-c", "echo $GITHUB_SHA"]

Um die in der Metadatendatei der Aktion definierten args an einen Docker-Container zu übergeben, der das Ausführungsformat im ENTRYPOINT verwendet, empfiehlt es sich, ein Shellskript namens entrypoint.sh zu erstellen, das über die ENTRYPOINT-Anweisung aufgerufen wird:

Beispiel für Dockerfile

# Container image that runs your code
FROM debian:9.5-slim

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

# Executes `entrypoint.sh` when the Docker container starts up
ENTRYPOINT ["/entrypoint.sh"]

Beispieldatei für entrypoint.sh

Mit dem obigen Dockerfile-Beispiel sendet GitHub die Metadaten-Datei der Aktion konfigurierten args als Argumente an entrypoint.sh. Füge die #!/bin/shshebang oben in der entrypoint.sh-Datei hinzu, um die POSIX-kompatible Shell des Systems explizit zu verwenden.

#!/bin/sh

# `$#` expands to the number of arguments and `$@` expands to the supplied `args`
printf '%d args:' "$#"
printf " '%s'" "$@"
printf '\n'

Dein Code muss ausführbar sein. Stelle sicher, dass die entrypoint.sh-Datei über execute-Berechtigungen verfügt, bevor du sie in einem Workflow verwendest. Du kannst die Berechtigung von deinem Terminal aus mit diesem Befehl ändern:

chmod +x entrypoint.sh

Wenn ein ENTRYPOINT-Shellskript nicht ausführbar ist, wird ein Fehler wie der folgende angezeigt:

Error response from daemon: OCI runtime create failed: container_linux.go:348: starting container process caused "exec: \"/entrypoint.sh\": permission denied": unknown

Befehlszeile

Wenn du in der Metadatendatei der Aktion args definierst, überschreibt args die CMD-Anweisung, die in der Dockerfile angegeben ist. Weitere Informationen finden Sie unter Metadatensyntax für GitHub Actions.

Wenn du in deiner Dockerfile die CMD-Anweisung verwendest, befolge die folgenden Richtlinien:

  1. Dokumentieren die erforderlichen Argumente in der README-Datei der Aktion, und lasse sie in der CMD-Anweisung weg.
  2. Verwende Standardwerte, die die Verwendung der Aktion ohne die Angabe von args ermöglichen.
  3. Wenn die Aktion ein --help-Flag oder etwas ähnliches verfügbar macht, verwende dies, damit die Aktion selbstdokumentierend wird.

Unterstützte Linux-Funktionen

GitHub Actions unterstützt die standardmäßigen Linux-Funktionen, die auch Docker unterstützt. Funktionen können weder hinzugefügt noch entfernt werden. Weitere Informationen zu den standardmäßigen Linux-Funktionen, die Docker unterstützt, findest du in der Docker-Dokumentation unter Linux-Kernelfunktionen. Weitere Informationen zu Linux-Funktionen findest du unter Übersicht über Linux-Funktionen auf den Linux-Man-Seiten.