Erstellen einer benutzerdefinierten GitHub-Aktion

Abgeschlossen

GitHub Actions ist ein leistungsstarkes Feature, das Sie vom Code bis hin in die Cloud begleitet und das auf Grundlage Ihres eigenen Repositorys. Hier erfahren Sie mehr über die verschiedenen Arten von GitHub-Aktionen und die Metadaten-, Syntax- und Workflowbefehle zum Erstellen benutzerdefinierter GitHub-Aktionen.

Arten von GitHub-Aktionen

Aktionen sind einzelne Aufgaben, mit denen Sie Ihre Entwicklungsworkflows anpassen können. Sie können eigene Aktionen erstellen, indem Sie benutzerdefinierten Code schreiben, der mit Ihrem Repository interagiert, um benutzerdefinierte Aufgaben auszuführen, oder indem Sie Aktionen verwenden, die von der GitHub-Community geteilt werden. Wenn Sie durch verschiedene Aktionen navigieren, werden Sie feststellen, dass es drei verschiedene Arten von Aktionen gibt: Docker-Containeraktionen,JavaScript-Aktionen und Aktionen für zusammengesetzte Ausführungsschritte. Im Folgenden werden die einzelnen Aktionstypen näher betrachtet:

Docker-Containeraktionen

Docker-Container packen die Umgebung mit dem GitHub Actions-Code. Dies bedeutet, dass die Aktion in einer konsistenten und zuverlässigen Umgebung ausgeführt wird, da sich alle Abhängigkeiten innerhalb dieses Containers befinden. Wenn die Aktion in einer bestimmten Umgebungskonfiguration ausgeführt werden muss, sind Docker-Container eine gute Möglichkeit, da Sie das Betriebssystem und die Tools anpassen können. Der Nachteil ist, dass Docker-Containeraktionen häufig langsamer sind als JavaScript-Aktionen, da der Auftrag den Container erstellen und abrufen muss.

Sie sollten sich grundlegende Kenntnisse über die Verwendung von Umgebungsvariablen und des Docker-Containerdateisystems aneignen, bevor Sie eine Docker-Containeraktion erstellen. Die Schritte zum Erstellen einer Docker-Containeraktion sind dann minimal und unkompliziert:

1. Erstellen Sie ein Dockerfile, um die Befehle zum Zusammenstellen des Docker-Images zu definieren.
2. Erstellen Sie eine action.yml-Metadatendatei, um die Eingaben und Ausgaben der Aktion zu definieren. Legen Sie in der Datei den runs: using:-Wert auf docker und den runs: image:-Wert auf Dockerfile fest.
3. Erstellen Sie eine entrypoint.sh-Datei, um das Docker-Image zu beschreiben.
4. Committen Sie Ihre Aktion, und pushen Sie sie mit den folgenden Dateien an GitHub: action.yml, entrypoint.sh, Dockerfile und README.md.

JavaScript-Aktionen

JavaScript-Aktionen können direkt auf dem Runnercomputer ausgeführt werden und den Aktionscode von der Umgebung trennen, die zum Ausführen der Aktion verwendet wird. Aus diesem Grund wird der Aktionscode vereinfacht und kann schneller als Aktionen in einem Docker-Container ausgeführt werden.

Als Voraussetzung für das Erstellen und Verwenden von gepackten JavaScript-Aktionen müssen Sie Node.js herunterladen, einschließlich npm. Als optionaler Schritt wird jedoch empfohlen, das Modul „GitHub Actions Toolkit Node.js“ zu verwenden. Dabei handelt es sich um eine Sammlung von Node.js-Paketen, mit denen Sie JavaScript-Aktionen schnell und konsistenter erstellen können.

Die Schritte zum Erstellen einer JavaScript-Aktion sind minimal und unkompliziert:

1. Erstellen Sie eine action.yml-Metadatendatei, um die Eingaben und Ausgaben der Aktion zu definieren, und melden Sie dem Aktionsrunner, wie diese JavaScript-Aktion ausgeführt werden soll.
2. Erstellen Sie eine index.js-Datei mit Kontextinformationen zu den Toolkitpaketen, dem Routing und anderen Funktionen der Aktion.
3. Committen Sie Ihre Aktion, und pushen Sie sie mit den folgenden Dateien an GitHub: action.yml, index.js, node_modules, package.json, package-lock.json und README.md.

Aktionen für zusammengesetzte Ausführungsschritte

Mit Aktionen für zusammengesetzte Ausführungsschritte können Sie Aktionen mithilfe von Shellskripts wiederverwenden. Sie können sogar mehrere Shellsprachen innerhalb derselben Aktion mischen. Wenn Sie über viele Shellskripts verfügen, um mehrere Aufgaben zu automatisieren, können Sie sie jetzt problemlos in eine Aktion umwandeln und für verschiedene Workflows wiederverwenden. Manchmal ist es einfacher, ein Shellskript zu schreiben, als JavaScript zu verwenden oder den Code in einem Docker-Container zu umschließen.

Verpackte zusammengesetzte Aktion

Verpackte zusammengesetzte Aktionen bündeln mehrere Schritte in einer wiederverwendbaren Einheit. Diese Aktionen werden in einem Repository definiert und können in Workflows in verschiedenen Repositorys referenziert werden. Das Packen einer zusammengesetzten Aktion vereinfacht Workflows, verringert die Duplizierung und verbessert die Wartungsfreundlichkeit.

Beim Erstellen einer gepackten zusammengesetzten Aktion werden die Schritte in einer einzelnen action.yml Datei definiert. Diese Datei gibt die Eingaben, Ausgaben und die Abfolge der auszuführenden Befehle oder Aktionen an. Verpackte zusammengesetzte Aktionen sind besonders nützlich, um sich wiederholende Aufgaben zu automatisieren oder mehrere Shellbefehle in einer einzigen wiederverwendbaren Aktion zu kombinieren.

Erstellen eines zusammengesetzten Qction

1. Einrichten eines Verzeichnisses für die zusammengesetzte Aktion

Sie müssen Ihre zusammengesetzte Aktion in einem eigenen Verzeichnis im Repository platzieren.

Beispielverzeichnisstruktur:

.github/actions/my-composite-action/
├── action.yml
└── scripts/
    └── my-script.sh

2. Definieren der action.yml Datei

Erstellen Sie im Verzeichnis "my-composite-action" eine action.yml Datei.

name: "My Composite Action"
description: "A reusable composite action that checks out code and sets up Node.js"

inputs:
  node-version:
    description: "The Node.js version to use"
    required: true

runs:
  using: "composite"
  steps:
    - name: Checkout repository
      uses: actions/checkout@v4

    - name: Set up Node.js
      uses: actions/setup-node@v4
      with:
        node-version: ${{ inputs.node-version }}

Anmerkung: Das feld "composite" gibt an, dass es sich bei dieser Aktion um eine zusammengesetzte Aktion handelt.

3. Verwenden der zusammengesetzten Aktion in einem Workflow

Sobald die zusammengesetzte Aktion erstellt wurde, kann sie in einem GitHub Actions-Workflow referenziert werden.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Use my composite action
        uses: ./.github/actions/my-composite-action
        with:
          node-version: '18'

Wenn Ihre zusammengesetzte Aktion aus einem anderen Repository freigegeben ist, verweisen Sie wie folgt darauf:

uses: owner/repository/.github/actions/my-composite-action@v1

Hinzufügen von Ausgaben zu einer zusammengesetzten Aktion

Zusammengesetzte Aktionen können Ausgaben definieren, mit denen Workflows Daten zwischen Schritten oder Aufträgen übergeben können. Ausgaben sind besonders hilfreich für das Freigeben von Ergebnissen oder berechneten Werten aus einer Aktion in eine andere.

Im folgenden Beispiel wird veranschaulicht, wie eine Ausgabe in einer zusammengesetzten Aktion definiert und verwendet wird:

Definieren einer Ausgabe in action.yml

Die action.yml Datei gibt eine Ausgabe mit dem Namen script-resultan. Diese Ausgabe ruft ihren Wert aus der result Ausgabe des run-script Schritts ab. Der run-script Schritt führt einen Bash-Befehl aus, um den Ausgabewert festzulegen.

outputs:
  script-result:
    description: "Result from the script"
    value: ${{ steps.run-script.outputs.result }}

runs:
  using: "composite"
  steps:
    - id: run-script
      run: echo "result=Success" >> $GITHUB_OUTPUT
      shell: bash

Verwenden der Ausgabe in einem Workflow

Sobald die zusammengesetzte Aktion erstellt wurde, kann auf die Ausgabe in einem Workflow zugegriffen werden. Ein Beispiel:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Run composite action
        id: my-action
        uses: ./.github/actions/my-composite-action

      - name: Display result
        run: echo "Script Result: ${{ steps.my-action.outputs.script-result }}"

In diesem Beispiel:

• Die zusammengesetzte Aktion wird mithilfe des uses Schlüsselworts aufgerufen.
• Greifen Sie mithilfe der Syntax auf die script-result Ausgabe steps.<step-id>.outputs.<output-name> zu.
• Zeigt das Ergebnis in den Workflowprotokollen an.

Definieren Sie Ausgaben in zusammengesetzten Aktionen, um wiederverwendbare und modulare Workflows zu erstellen. Dieser Ansatz vereinfacht die Datenfreigabe und verbessert die Wartung.

Bewährte Methoden für zusammengesetzte Aktionen

Beste Praxis	Beschreibung
Verwenden der Versionsverwaltung	Verwenden Sie ein v1 Tag, um auf stabile Version 1 zu verweisen.
Halten Sie Aktionen modular	Gruppieren Sie verwandte Schritte innerhalb einer zusammengesetzten Aktion.
Dokumenteingaben und -ausgaben	Fügen Sie Beschreibungen für Eingaben/Ausgaben in action.yml.
Testen vor der Veröffentlichung	Überprüfen Sie die zusammengesetzte Aktion in einem Test-Repository.

Zusammengesetzte Aktion in einem Workflow

Zusammengesetzte Aktionen sind eine leistungsstarke Möglichkeit, Workflows zu vereinfachen, indem sie mehrere Schritte in eine wiederverwendbare Einheit bündeln. Mit diesen Aktionen können Sie eine Abfolge von Befehlen oder Aktionen in einer einzelnen action.yml Datei definieren, wodurch die Verwaltung und Wiederverwendung von Logik in workflows vereinfacht wird.

Vorteile zusammengesetzter Aktionen:

• Wiederverwendbarkeit : Definieren Sie Aktionen einmal, und verwenden Sie sie in mehreren Workflows.
• Verwundbarkeit – Reduzieren Sie die Duplizierung, indem Sie die Logik in einer einzigen Aktion zentralisieren.
• Modularität – Kombinieren Sie mehrere Shellbefehle oder andere Aktionen in einer einzigen Einheit.

Entwickeln einer Aktion zum Einrichten einer CLI auf GitHub Actions-Läufern

Viele CI/CD-Workflows erfordern eine bestimmte Version eines CLI-Tools , um mit Clouddiensten zu interagieren, Infrastruktur zu verwalten oder Skripts auszuführen. Obwohl von GitHub gehostete Läufer mit vielen Tools vorinstalliert sind, enthalten sie möglicherweise nicht die genaue Version, die Ihr Workflow benötigt, insbesondere, wenn es sich um eine ältere oder nicht unterstützte Version handelt. Anstatt die erforderliche CLI-Version in jedem Workflow zu installieren, können Sie eine wiederverwendbare GitHub-Aktion erstellen, die:

• Stellt eine konsistente Installation der erforderlichen CLI-Version für aufträgeübergreifend sicher.
• Vereinfacht Workflows, indem die Installationslogik zentralisiert wird.
• Optimiert die Zwischenspeicherung für eine schnellere Workflowausführung.

So entwickeln Sie eine CLI-Einrichtungsaktion

Eine CLI-Setupaktion ist eine JavaScript-basierte Aktion , die eine CLI auf einem GitHub-Runner installiert und konfiguriert.

Schritte zum Erstellen der Aktion:

Schritt 1: Einrichten des Aktionsverzeichnisses

Führen Sie die folgenden Schritte aus, um das Verzeichnis für Ihre CLI-Setupaktion manuell zu erstellen:

1. Navigieren Sie zu Ihrem Repository

2. Erstellen eines neuen Verzeichnisses für die Aktion
   Erstellen Sie ein neues Verzeichnis mit dem Namen my-cli-action innerhalb des Ordners .github/actions . Dadurch wird sichergestellt, dass Ihre Aktion organisiert ist und die empfohlene Struktur von GitHub für benutzerdefinierte Aktionen folgt.

3. Navigieren zum neuen Verzeichnis
   Wechseln Sie in das neu erstellte Verzeichnis, um mit dem Hinzufügen von Dateien für Ihre Aktion zu beginnen:

4. Überprüfen der Verzeichnisstruktur
   Nach dem Erstellen des Verzeichnisses sollte Ihre Repositorystruktur wie folgt aussehen:

your-repository/
├── .github/
│   ├── actions/
│   │   ├── my-cli-action/

Sie können nun mit dem Erstellen der action.yml Datei und anderen erforderlichen Dateien für Ihre CLI-Setupaktion fortfahren.

Schritt 2: Definieren der action.yml Metadatendatei

Erstellen Sie eine action.yml Datei, um die Aktion zu beschreiben.

name: "Setup MyCLI"
description: "Installs MyCLI and adds it to the PATH"
author: "Your Name"

inputs:
  version:
    description: "The CLI version to install"
    required: false
    default: "latest"

runs:
  using: "node16"
  main: "index.js"

Gründe für die Verwendung: node16? Diese Aktion führt JavaScript-Code mit Node.js 16 aus.

Schritt 3: Erstellen eines JavaScript-Skripts zum Installieren der CLI

Erstellen Sie im selben Verzeichnis eine Datei mit dem Namen index.js, und fügen Sie den folgenden Code hinzu:

const core = require('@actions/core');
const { execSync } = require('child_process');

async function run() {
  try {
    const version = core.getInput('version') || 'latest';
    
    console.log(`Installing MyCLI version: ${version}...`);

    execSync(`curl -fsSL https://cli.example.com/install.sh | sh`, { stdio: 'inherit' });

    console.log("MyCLI installed successfully.");
  } catch (error) {
    core.setFailed(`Installation failed: ${error.message}`);
  }
}

run();

Der obige JavaScript-Code verwendet "core.getInput()", um die als Eingabe angegebene CLI-Version abzurufen. Anschließend wird ein curl-Befehl ausgeführt, um die CLI herunterzuladen und zu installieren. Wenn der Installationsprozess fehlschlägt, verwendet die Aktion "core.setFailed()", um den Workflow als fehlgeschlagen zu markieren.

Schritt 4: Lokales Testen der Aktion

Bevor Sie die Aktion in einem Workflow verwenden, testen Sie sie auf einem von GitHub gehosteten Runner.
Erstellen Sie eine Workflowdatei (GITHUB/workflows/test.yml) in Ihrem Repository:

name: Test MyCLI Setup

on:
  push:
    branches:
      - main
      - feature/*

1. Auslösen des Workflows
Der Workflow wird auf Pushs an die Haupt-Verzweigung und alle Verzweigung ausgelöst, die mit dem Feature/*-Muster übereinstimmen. Sie können dies an die Verzweigungsstrategie Ihres Repositorys anpassen.

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

2. Klonen des Repositorys
Die Aktionen/checkout@v4 Aktion wird verwendet, um das Repository auf den Läufer zu klonen. Dadurch wird sichergestellt, dass der Workflow Zugriff auf die Dateien des Repositorys hat.

      - name: Install MyCLI
        uses: ./.github/actions/my-cli-action
        with:
          version: '1.2.3'

3. Ausführen der benutzerdefinierten Aktion
Die verwendung: ./.github/actions/my-cli-action line verweist lokal auf die benutzerdefinierte Aktion. Stellen Sie sicher, dass das Aktionsverzeichnis und action.yml Datei ordnungsgemäß eingerichtet sind. Die Versionseingabe gibt die zu installierende CLI-Version an– in diesem Fall Version 1.2.3.

      - name: Verify CLI Installation
        run: |
          echo "Checking MyCLI version..."
          mycli --version

4. Überprüfen der CLI-Installation
In diesem Schritt wird ein Shellbefehl ausgeführt, um zu überprüfen, ob die CLI erfolgreich installiert wurde. Es überprüft die Version der installierten CLI, indem mycli --version ausgeführt wird.

Lokales Testen

Verwenden Sie das act CLI-Tool, um diesen Workflow lokal zu testen:

act -j test

Dadurch wird die GitHub Actions-Umgebung auf Ihrem lokalen Computer simuliert, sodass Sie den Workflow debuggen und überprüfen können, bevor Sie Änderungen pushen.

Optimierungstipp: Zwischenspeichern

Um die Workflowleistung zu verbessern, speichern Sie das CLI-Installationsverzeichnis mithilfe der actions/cache Aktion zwischen:

      - name: Cache MyCLI
        uses: actions/cache@v4
        with:
          path: ~/.mycli
          key: mycli-${{ runner.os }}-${{ inputs.version }}

Dadurch wird sichergestellt, dass nachfolgende Ausführung die zwischengespeicherte CLI-Installation wiederverwendet, wodurch die Setupzeit reduziert wird.

Bewährte Methoden für CLI-Setupaktionen

Bewährte Methode	Beschreibung
Verwenden der Versionsverwaltung	Zulassen, dass Benutzer eine CLI-Version über inputs.version.
Ordnungsgemäße Behandlung von Fehlern	Wird verwendet core.setFailed() , um Fehler zu beenden.
Cache CLI-Installation	Optimieren der Workflowleistung mithilfe von actions/cache.
Dokumentation bereitstellen	Erläutern der Verwendung und Eingaben in README.md.

Behandeln von Problemen mit JavaScript-Aktionen

Beim Arbeiten mit JavaScript-basierten GitHub-Aktionen können unerwartetes Verhalten, Fehler oder Fehler während der Workflowausführung auftreten. Diese Lektion bietet Techniken und Tools, mit denen Sie Probleme in Ihren JavaScript-Aktionen identifizieren und beheben können.

Häufige Problembehandlungsszenarien

Das Problem	Mögliche Ursache	Vorgeschlagener Fix
Aktion schlägt mit einer Stapelablaufverfolgung fehl	Syntax- oder Laufzeitfehler in index.js	Verwenden console.log() und Überprüfen von Protokollen
Eingaben sind undefined	Falscher Eingabename oder fehlende Eingabe	Überprüfen action.yml und Übergeben von Eingaben
Umgebungsvariablen nicht festgelegt	core.exportVariable oder process.env nicht ordnungsgemäß verwendet	Überprüfen der Codeeinstellung für die Variablen
Datei nicht gefunden	Fehlende relative Pfade	Verwenden __dirname oder vollständige Pfade zu Dateien
Der Cache wird nicht wiederhergestellt.	Falsch key oder path Werte	Überprüfen der Cachekonfiguration und schlüssel

Verwenden der Protokollierung für das Debuggen

Protokollieren von Nachrichten mit core.info, core.debugund console.log

const core = require('@actions/core');

core.info("This is an info message");
core.debug("This is a debug message");
console.log("This is a raw console log");

✅ Verwenden Sie core.debug für Debugprotokolle – diese werden nur angezeigt, wenn ACTIONS_STEP_DEBUG auf "true" festgelegt ist.

Debugprotokollierung aktivieren

Sie können Debugprotokolle auf Schrittebene aktivieren, indem Sie den folgenden geheimen Schlüssel festlegen:

ACTIONS_STEP_DEBUG=true

Um Runner-Diagnoseprotokolle zu aktivieren, legen Sie Folgendes fest:

ACTIONS_RUNNER_DEBUG=true

Festlegen geheimer Schlüssel für das Debuggen

1. Wechseln Sie zu Ihrem GitHub-Repository.
2. Navigieren Sie zu "Geheime Einstellungen">und "Variablenaktionen>".
3. Fügen Sie neue geheime Schlüssel mit den folgenden Namen und Werten hinzu:
   • ACTIONS_STEP_DEBUG: true
   • ACTIONS_RUNNER_DEBUG: true

Überprüfen von Workflowprotokollen

Wenn ein Workflow fehlschlägt, klicken Sie auf der Registerkarte "Aktionen" auf den fehlgeschlagenen Auftrag. Erweitern Sie jeden Schritt auf:

• Detaillierte Protokolle anzeigen
• Standardausgabe überprüfen (Stdout)
• Anzeigen des Exit-Codes von Skripts
• Identifizieren unbehandelter Ausnahmen

🔍 Beispielprotokollausgabe

Error: Cannot find module '@actions/core'
Require stack:
- /home/runner/work/_actions/my-org/my-action/index.js

✅ Fix: Führen Sie npm install @actions/core and commit node_modules (oder verwenden Sie ncc, um die Aktion zu bündeln).

Lokales Testen ihrer Aktion

Verwenden Sie Act – ein CLI-Tool zum lokalen Ausführen von GitHub-Aktionen. Beispiel:

act -j test

🛠 Stellen Sie sicher, dass Sie Ihre GitHub-Umgebung beim lokalen Testen ordnungsgemäß simulieren.

Fehler ordnungsgemäß behandeln

Ausnahmen abfangen und mit hilfreichen Nachrichten fehlschlagen:

try {
  // your logic
} catch (error) {
  core.setFailed(`Action failed with error: ${error.message}`);
}

🔁 Dadurch wird sichergestellt, dass GitHub den Workflow beim Fehler beendet und lesbare Protokolle bereitstellt.

Bewährte Methoden zum Debuggen von JavaScript-Aktionen

Übung	Beschreibung
Verwenden von core.debug()	Ausführliche Protokolle ausblenden, es sei denn, das Debuggen ist aktiviert.
Überprüfen action.yml	Stellen Sie sicher, dass Eingaben und Ausgaben korrekt definiert sind.
Bundlecode	Wird @vercel/ncc verwendet, um JavaScript in eine einzelne Datei zu kompilieren. Dadurch werden Abhängigkeiten reduziert und sichergestellt, dass alle erforderlichen Module enthalten sind, wodurch Laufzeitfehler vermieden werden, die durch fehlende Dateien verursacht werden.
Testen mit Akt	Simulieren Sie die Ausführung lokal für schnellere Iterationen.
Verwenden von try/catch	Verhindern, dass Workflows im Hintergrund fehlschlagen.

Behandeln von Problemen mit Docker-Containeraktionen

Docker-Containeraktionen sind leistungsfähig zum Kapseln komplexer Tools und Umgebungen in GitHub-Aktionen-Workflows. Das Debuggen dieser Aktionen kann jedoch aufgrund ihrer isolierten Laufzeitumgebung schwieriger sein als JavaScript-Aktionen. Diese Lektion führt Sie durch das Identifizieren, Diagnostizieren und Beheben von Problemen mit Docker-basierten Aktionen.

Häufige Probleme in Docker-Containeraktionen

Das Problem	Ursache	Vorgeschlagener Fix
Aktion kann nicht gestartet werden	ENTRYPOINT oder CMD falsch konfiguriert	Bestätigen, dass Dockerfile ordnungsgemäß verwendet wird ENTRYPOINT
Fehlende Abhängigkeiten	Nicht installierte oder falsch konfigurierte Abhängigkeiten	Stellen Sie sicher, dass alle Pakete im Image installiert sind.
Eingaben nicht empfangen	INPUT_ Auf Umgebungsvariablen wurde nicht zugegriffen	Verwenden process.env.INPUT_<INPUT_NAME> (oder Shellentsprechung)
Datei nicht gefunden	Falscher Dateipfad innerhalb des Containers	Verwenden absoluter Pfade oder Überprüfen der Verzeichnisstruktur
Berechtigung verweigert	Datei- oder Skriptberechtigungen fehlen	Hinzufügen RUN chmod +x <script> in Dockerfile
Netzwerkbezogene Fehler	Auf externe Dienste kann nicht zugegriffen werden	Überprüfen von Netzwerkeinstellungen und Wiederholungslogik

Grundlegendes zum Lebenszyklus von Docker-Aktionen

Vor der Problembehandlung ist es hilfreich, zu verstehen, wie Docker-Containeraktionen ausgeführt werden.

1. Workflowtrigger

Ein GitHub Actions-Workflow beginnt als Reaktion auf ein konfiguriertes Ereignis , z. B. ein push, pull_requestoder ein manuelles workflow_dispatchEreignis .

2. Einrichten des Runners

GitHub stellt einen neuen virtuellen Computer (der Runner) bereit, um den Workflow auszuführen. Der Läufer bereitet die Umgebung vor, indem Aktionsdefinitionen heruntergeladen und Abhängigkeiten aufgelöst werden.

3. Lösung für Maßnahmen

Wenn die Aktion in der runs.using: docker Datei angibtaction.yml, erkennt GitHub sie als Docker-basierte Aktion.

4. ImageBuild oder Pull

GitHub erstellt das Docker-Image, das in den Aktionen Dockerfile definiert ist, oder ruft ein vordefiniertes Image ab, falls angegeben. Dieses Bild definiert die Umgebung, in der der Aktionscode ausgeführt wird.

5. Containerausführung

Der Läufer startet den Docker-Container, stellt den Arbeitsbereich her und fügt Umgebungsvariablen ein, einschließlich geheimer Schlüssel und Eingaben, die im Workflow definiert sind.

6. Einstiegspunktläufe

GitHub führt den entrypoint Befehl aus der Dockerfile-Datei innerhalb des Containers aus. Hier wird die benutzerdefinierte Aktionslogik ausgeführt, in der Regel ein Skript oder eine Anwendung.

7. Ergebnisbehandlung

Alle Ausgaben, die von der Containeraktion festgelegt werden, werden vom Läufer erfasst und an nachfolgende Schritte im Workflow übergeben. Nach Abschluss des Vorgangs wird der Container heruntergefahren, und der Läufer wird verworfen.

Hinweis: Docker-Containeraktionen werden in einer sauberen, isolierten Umgebung ausgeführt. Dateisystemstatus, installierte Tools und Umgebungsvariablen müssen in der Dockerfile-Datei definiert werden.

Debuggingverfahren

1. Protokollierung hinzufügen

Verwenden Sie Echo-, Printf- oder Protokollierungsanweisungen in Ihrem Einstiegspunktskript:

echo "Starting Docker action..."
echo "Input VALUE: $INPUT_VALUE"

Protokollieren Sie alle kritischen Eingaben und Schritte, um zu diagnostizieren, wo der Fehler auftritt.

2. Lokal erstellen und testen

Verwenden Sie Docker auf Ihrem Computer, um das Containerverhalten zu simulieren:

docker build -t my-action .
docker run -e INPUT_NAME=value my-action

Stellen Sie sicher, dass Umgebungsvariablen die GitHub-Sätze nachahmen.

3. Verwenden Sie die Act CLI, um GitHub-Workflows zu simulieren.

Installieren Sie Act, um Ihre GitHub-Workflows lokal auszuführen:

act -j test-job

Eignet sich hervorragend zum Testen von Docker-Aktionen in Workflows, ohne auf GitHub zu übertragen.

4. Überprüfen der Dockerfile-Konfiguration

Stellen Sie sicher, dass Sie ENTWEDER ENTRYPOINT oder CMD definieren. Kopieren Sie Ihre Skripts in das Bild, und erteilen Sie ihnen die Berechtigung zum Ausführen:

COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]

5. Überprüfen von GitHub-Protokollen

Klicken Sie auf eine fehlgeschlagene Workflowausführung, erweitern Sie jeden Schritt, und überprüfen Sie Folgendes:

• Docker-Buildprotokolle
• Standardausgabe und Standardfehler aus dem Container
• Exitcodes und Stapelüberwachungsprotokolle 🔍 zeigen häufig fehlende Pakete, Syntaxprobleme oder Berechtigungsfehler an.

Beispiel: Einstiegspunktfehler

Error: container_linux.go:380: starting container process caused "exec: \"/entrypoint.sh\": permission denied"

✅ Fix: Fügen Sie RUN chmod +x /entrypoint.sh in Ihrer Dockerfile-Datei hinzu.

Zuordnung von Umgebungsvariablen

GitHub-Eingabe	Docker-Umgebungsvariable
with: name: test	INPUT_NAME=test
GITHUB_WORKSPACE	Zugeordnet in /github/workspace
GITHUB_EVENT_NAME	Ereignis, das den Workflow ausgelöst hat

echo "Input was $INPUT_NAME"
echo "Working dir: $GITHUB_WORKSPACE"

Verwenden von Geheimschlüsseln zur Problembehandlung

Aktivieren Sie zusätzliche Protokollierung, indem Sie diese geheimen Schlüssel zu Ihrem Repository oder Ihrer Organisation hinzufügen:

Geheim	Beschreibung des Dataflows
ACTIONS_STEP_DEBUG	Aktiviert die Debugprotokollierung
ACTIONS_RUNNER_DEBUG	Aktiviert die Läuferdiagnose

Bewährte Methoden für das Debuggen von Docker-Aktionen

Beste Praxis	Hintergründe
Verwenden sie die Protokollierung großzügig	Hilft bei der Ablaufverfolgung von Fehlerpunkten
Immer chmod +x festlegen	Vermeiden von Berechtigungsfehlern für Shellskripts
Überprüfen von Eingaben in Ihrem Skript	Erfassen fehlender oder falsch formatierter Eingaben frühzeitig
Minimieren von Containerabhängigkeiten	Kleinere Bilder sind einfacher zu debuggen
Lokales Testen mit Docker-Ausführung oder -Aktion	Schnellere Iterationen und sofortiges Feedback