Informationen zu benutzerdefinierten Aktionen

Informationen zu benutzerdefinierten Aktionen

Zum Erstellen von Aktionen kannst du benutzerdefinierten Code schreiben, der mit deinem Repository auf die gewünschte Weise interagiert und sich dabei beispielsweise in die APIs von GitHub und in öffentlich zugängliche Drittanbieter-APIs integriert. Beispielsweise kann eine Aktion npm-Module veröffentlichen, SMS-Warnungen senden, wenn dringende Probleme erstellt werden, oder produktionsbereiten Code bereitstellen.

Aktionen können direkt auf einem Computer oder in einem Docker-Container laufen. Du kannst für eine Aktion die Eingabe, die Ausgabe und die Umgebungsvariablen definieren.

Arten von Aktionen

Du kannst Docker-Container-, JavaScript- und zusammengesetzte Aktionen erstellen. Aktionen benötigen eine Metadaten-Datei, in der die Eingaben, Ausgaben und der Haupteinstiegspunkt für die Aktion definiert werden. Der Name der Metadatendatei muss entweder action.yml oder action.yaml lauten. Weitere Informationen findest du unter Metadatensyntax für GitHub Actions.

Docker-Containeraktionen

Docker-Container packen die Umgebung mit dem GitHub Actions-Code. So entsteht eine konsistentere, zuverlässigere Arbeitseinheit, da der Aktionsbenutzer sich nicht um Tools oder Abhängigkeiten kümmern muss.

Mit einem Docker-Container kannst du bestimmte Versionen eines Betriebssystems sowie bestimmte Abhängigkeiten, Tools und Code verwenden. Bei Aktionen, die in einer bestimmten Umgebungs-Konfiguration laufen müssen, ist Docker eine ideale Option, da du das Betriebssystem und die Tools anpassen kannst. Wegen der Latenz für das Erstellen und Abrufen des Containers sind Docker-Container-Aktionen langsamer als JavaScript-Aktionen.

Docker Container-Aktionen können nur auf Runnern mit einem Linux-Betriebssystem ausgeführt werden. 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.

JavaScript-Aktionen

JavaScript-Aktionen können direkt auf einem Runner-Rechner laufen und den Aktions-Code von der Umgebung trennen, in der der Code läuft. Eine JavaScript-Aktion enthält einfacheren Aktionscode und läuft schneller als eine Docker-Container-Aktion.

Um sicherzustellen, dass deine JavaScript-Aktionen mit allen GitHub-gehosteten Runnern (Ubuntu, Windows und macOS) kompatibel sind, sollte der von dir geschriebene paketierte JavaScript-Code reines JavaScript sein und nicht von anderen Binärdateien abhängig sein. JavaScript-Aktionen werden direkt auf dem Runner ausgeführt und verwenden Binärdateien, die bereits im Runner-Image vorhanden sind.

Wenn du ein Node.js Projekt entwickelst, bietet das GitHub Actions Toolkit Pakete, die du in deinem Projekt verwenden kannst, um die Entwicklung zu beschleunigen. Weitere Informationen findest du im Repository für Aktionen/Toolkits.

Zusammengesetzte Aktionen

Mit einer zusammengesetzten Aktion kannst du mehrere Workflowschritte in einer Aktion kombinieren. Du kannst diese Funktion zum Beispiel nutzen, um mehrere Ausführungsbefehle in einer Aktion zu bündeln und dann einen Workflow einzurichten, der die gebündelten Befehle in einem einzigen Schritt mit dieser Aktion ausführt. Ein Beispiel findest du unter Erstellen einer zusammengesetzten Aktion.

Ort für eine Aktion auswählen

Wenn du eine Aktion entwickelst, die von anderen Personen genutzt werden soll, empfehlen wir, die Aktion in ihrem eigenen Repository zu belassen, also nicht mit anderem Anwendungscode zu einem Bundle zusammenzufassen. Damit kannst du die Aktion wie jede andere Software versionieren, nachverfolgen und veröffentlichen.

Um Aktionen für dein gesamtes Unternehmen freizugeben, ohne diese für den öffentlichen Zugriff zu veröffentlichen, kannst du die Aktionen in einem internen Repository speichern und dieses dann so konfigurieren, dass der Zugriff auf GitHub Actions-Workflows in anderen Repositorys im Besitz derselben Organisation oder einer anderen Organisation im Unternehmen zugelassen ist. Weitere Informationen finden Sie unter Freigeben von Aktionen und Workflows in deinem Unternehmen.

Du kannst die Dateien der Aktion an einem beliebigen Speicherort in deinem Repository speichern. Wenn du planst, Aktions-, Workflow- und Anwendungscode in einem einzigen Repository zu kombinieren, empfehlen wir, Aktionen im Verzeichnis .github zu speichern. Beispiel: .github/actions/action-a und .github/actions/action-b.

Sicherstellen der Kompatibilität mit anderen Plattformen

Viele Personen greifen über eine andere Domäne als GitHub.com auf GitHub zu, z. B. über GHE.com oder eine benutzerdefinierte Domäne für GitHub Enterprise Server.

Um sicherzustellen, dass deine Aktion mit anderen Plattformen kompatibel ist, solltest du keine hartcodierten Verweise auf API-URLs wie https://api.github.com verwenden. Stattdessen kannst du Folgendes tun:

• Verwenden von Umgebungsvariablen (siehe Speichern von Informationen in Variablen):

  • Verwende für die REST-API die Umgebungsvariable GITHUB_API_URL.
  • Verwende für GraphQL die Umgebungsvariable GITHUB_GRAPHQL_URL.

• Verwende ein Toolkit wie @actions/github, das automatisch die richtigen URLs festlegen kann.

Using release management for actions (Verwenden der Releaseverwaltung für Aktionen)

In diesem Abschnitt erfährst du, wie du mithilfe der Releaseverwaltung Updates auf planbare Weise an deine Aktionen verteilen kannst.

Bewährte Methoden für die Releaseverwaltung

Wenn du eine Aktion entwickelst, die auch von anderen genutzt werden soll, empfehlen wir dir, die Verteilung von Updates mithilfe der Releaseverwaltung zu steuern. Die Benutzer*innen können erwarten, dass die Patchversion einer Aktion die notwendigen kritischen Fixes und Sicherheitspatches enthält und dennoch weiterhin mit ihren vorhandenen Workflows kompatibel ist. Du solltest die Veröffentlichung einer neuen Hauptversion in Betracht ziehen, wenn sich deine Änderungen auf die Kompatibilität auswirken.

Bei diesem Releaseverwaltungsansatz sollten Benutzer nicht auf den Master Zweig einer Aktion verweisen, da dieser wahrscheinlich den neuesten Code enthält und daher möglicherweise instabil ist. Stattdessen kannst du deinen Benutzern empfehlen, bei Verwendung deiner Aktion eine Hauptversion anzugeben und nur dann auf eine spezifischere Version zu verweisen, wenn sie auf Probleme stoßen.

Um eine bestimmte Version einer Aktion zu verwenden, kannst du deinen GitHub Actions-Workflow für ein Tag, den SHA eines Commits oder einen Branch für ein Release konfigurieren.

Verwenden von Tags für die Releaseverwaltung

Es wird empfohlen, Tags für die Releaseverwaltung von Aktionen zu verwenden. Bei diesem Ansatz können deine Benutzer leicht zwischen Haupt- und Nebenversionen unterscheiden:

• Erstelle und überprüfe ein Release in einem Releasebranch (z. B. release/v1 ), bevor du das Versionstag (z. B. v1.0.2) erstellst.
• Erstelle ein Release mittels semantischer Versionierung. Weitere Informationen findest du unter Veröffentlichungen in einem Repository verwalten.
• Verschiebe das Hauptversionstag (z. B. v1, v2) so, dass es auf die Git-Referenz der aktuellen Version zeigt. Weitere Informationen findest du unter Git-Grundlagen – Tagging.
• Führe ein neues Hauptversionstag (v2) für Änderungen ein, die vorhandene Workflows unterbrechen. Eine störende Änderung liegt beispielsweise vor, wenn die Eingabe einer Aktion geändert wird.
• Hauptversionen können zunächst mit einem beta-Tag veröffentlicht werden, um ihren Status anzugeben, z. B. v2-beta. Das -beta-Tag kann dann später wieder entfernt werden.

Dieses Beispiel zeigt, wie ein Benutzer auf ein Tag für ein Hauptrelease verweisen kann:

steps:
    - uses: actions/javascript-action@v1

Dieses Beispiel zeigt, wie ein Benutzer auf ein Tag für ein bestimmtes Patchrelease verweisen kann:

steps:
    - uses: actions/javascript-action@v1.0.1

Verwenden von Branches für die Releaseverwaltung

Wenn du lieber Branchnamen für die Releaseverwaltung verwendest, zeigt dir dieses Beispiel, wie du auf einen benannten Branch verweisen kannst:

steps:
    - uses: actions/javascript-action@v1-beta

Verwenden des SHA eines Commits für die Releaseverwaltung

Jeder Git-Commit erhält einen berechneten SHA-Wert, der eindeutig und unveränderlich ist. Die Benutzer deiner Aktion ziehen es vielleicht vor, sich auf den SHA-Wert eines Commits zu verlassen, da dieser Ansatz zuverlässiger ist als das Angeben eines Tags, das gelöscht oder verschoben werden könnte. Das bedeutet jedoch, dass die Benutzer keine weiteren Updates erhalten, die für die Aktion vorgenommen werden. Du musst den vollständigen SHA-Wert eines Commits verwenden, keinen abgekürzten Wert.

steps:
    - uses: actions/javascript-action@a824008085750b8e136effc585c3cd6082bd575f

Eine README-Datei für die Aktion erstellen

Wenn du deine Aktion öffentlich bereitstellen möchten, empfehlen wir, eine README-Datei zu erstellen, damit andere Benutzer verstehen, wie die Aktion zu verwenden ist. Du kannst diese Informationen in deine README.md aufnehmen:

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

Unterschiede zwischen GitHub Actions und GitHub Apps

GitHub Marketplace bietet Tools, um deinen Workflow zu verbessern. Wenn du die Unterschiede und die Vorteile der einzelnen Tools verstehst, kannst du das beste Tool für deinen Auftrag auswählen. Weitere Informationen zum Erstellen von Apps findest du unter Informationen zum Erstellen von GitHub-Apps.

Stärken von GitHub Aktionen und GitHub Apps

Sowohl GitHub Actions als auch GitHub Apps bieten Möglichkeiten zur Entwicklung von Automatisierungs- und Workflowtools, aber durch ihre jeweiligen Stärken sind sie für unterschiedliche Zwecke von Nutzen.

GitHub Apps:

• Laufen dauerhaft und können schnell auf Ereignisse reagieren.
• Funktionieren hervorragend, wenn persistente Daten benötigt werden.
• Funktionieren am besten mit API-Anforderungen, die nicht zeitaufwändig sind.
• Laufen auf deinem Server oder auf deiner Rechner-Infrastruktur.

GitHub Actions:

• Bieten Automatisierung für eine kontinuierliche Integration und kontinuierliche Bereitstellung.
• Können direkt auf Runner-Maschinen oder in Docker-Containern laufen.
• Können auch Zugriff auf einen Klon deines Repositorys einschließen und dadurch Bereitstellungs- und Veröffentlichungstools, Codeformatierern und Befehlszeilentools den Zugriff auf deinen Code erlauben.
• Erfordern weder, dass du Code noch eine App bereitstellst.
• Du benötigst eine einfache Schnittstelle zum Erstellen und Verwenden von Geheimnissen. Dadurch können die Aktionen mit Diensten von Drittanbietern interagieren, ohne die Anmelde-Informationen des Aktions-Benutzers speichern zu müssen.

Weitere Informationsquellen

• Workflow commands for GitHub Actions (Workflowbefehle für GitHub Actions)