About custom actions

About custom actions

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. Mit einer Aktion können Sie beispielsweise npm-Module veröffentlichen, SMS-Nachrichten bei dringenden Problemen senden oder produktionsreifen Code bereitstellen.

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

Arten von Aktionen

Sie können Docker-Container- und JavaScript-Aktionen erstellen. Für Aktionen wird eine Metadaten-Datei benötigt, in der die Eingaben, Ausgaben und der Haupteinstiegspunkt für die Aktion definiert werden. Der Dateiname für die Metadaten muss entweder action.yml oder action.yaml sein. Weitere Informationen findest Du unter „Metadatensyntax für GitHub Actions“.

Docker-Containeraktionen

Docker-Container paketieren 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 können Sie bestimmte Versionen eines Betriebssystems sowie bestimmte Abhängigkeiten, Tools und Code verwenden. Bei Aktionen, die in einer bestimmten Umgebungskonfiguration ausgeführt werden müssen, ist Docker eine ideale Option, da Sie das Betriebssystem und die Tools anpassen können. 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 von selbst-gehosteten Läufern findest Du unter"Über selbst-gehostete Läufer".

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 umfasst einfacheren Aktionscode und lässt sich schneller ausführen als eine Docker-Container-Aktion.

Um sicherzustellen, dass Deine JavaScript-Aktionen mit allen GitHub-gehosteten Läufern (Ubuntu, Windows und macOS) kompatibel sind, sollte der von Dir geschriebene paketierte JavaScript-Code reines JavaScript sein und sich nicht auf andere Binärdateien verlassen. JavaScript-Aktionen werden direkt auf dem Läufer ausgeführt und verwenden Binärdateien, die bereits in der virtuellen Umgebung vorhanden sind.

Wenn Sie ein Node.js Projekt entwickeln, bietet das GitHub Actions Toolkit Pakete, die Sie in Ihrem Projekt verwenden können, um die Entwicklung zu beschleunigen. Weitere Informationen findest Du im Repository actions/toolkit.

Composite Actions

A composite action allows you to combine multiple workflow steps within one action. For example, you can use this feature to bundle together multiple run commands into an action, and then have a workflow that executes the bundled commands as a single step using that action. To see an example, check out "Creating a composite action".

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.

You can store the action's files in any location in your repository. Wenn der Aktions-, der Workflow- und der Anwendungscode in einem einzigen Repository abgelegt werden sollen, empfehlen wir, die Aktionen im Verzeichnis .github zu speichern. Beispiel: .github/actions/action-a und .github/actions/action-b.

Compatibility with GitHub Enterprise Server

To ensure that your action is compatible with GitHub Enterprise Server, you should make sure that you do not use any hard-coded references to GitHub API URLs. You should instead use environment variables to refer to the GitHub API:

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

For more information, see "Default environment variables."

Using release management for actions

This section explains how you can use release management to distribute updates to your actions in a predictable way.

Good practices for release management

If you're developing an action for other people to use, we recommend using release management to control how you distribute updates. Users can expect an action's major version to include necessary critical fixes and security patches, while still remaining compatible with their existing workflows. You should consider releasing a new major version whenever your changes affect compatibility.

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. Instead, you can recommend that your users specify a major version when using your action, and only direct them to a more specific version if they encounter issues.

To use a specific action version, users can configure their GitHub Actions workflow to target a tag, a commit's SHA, or a branch named for a release.

Using tags for release management

We recommend using tags for actions release management. Using this approach, your users can easily distinguish between major and minor versions:

• Erstellen und überprüfen Sie eine Version auf einem Release-Zweig (z. B. release/v1), bevor Sie das Release-Tag erstellen (z. B. v1.0.2).
• Erstellen Sie eine Version mit semantischer Versionierung. Weitere Informationen finden Sie unter „Veröffentlichungen erstellen“.
• Verschieben Sie das Hauptversions-Tag (z. B. v1, v2), um auf die Git-Ref der aktuellen Version zu verweisen. Weitere Informationen findest Du unter „Git-Grundlagen - Tagging“.
• Führen Sie ein neues Hauptversions-Tag (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 entfernt werden, wenn es fertig ist.

This example demonstrates how a user can reference a major release tag:

Schritte:
    - verwendet: actions/javascript-action@v1

This example demonstrates how a user can reference a specific patch release tag:

Schritte:
    - verwendet: actions/javascript-action@v1.0.1

Using branches for release management

If you prefer to use branch names for release management, this example demonstrates how to reference a named branch:

Schritte:
    - verwendet: actions/javascript-action@v1-beta

Using a commit's SHA for release management

Each Git commit receives a calculated SHA value, which is unique and immutable. Your action's users might prefer to rely on a commit's SHA value, as this approach can be more reliable than specifying a tag, which could be deleted or moved. However, this means that users will not receive further updates made to the action. Using a commit's full SHA value instead of the abbreviated value can help prevent people from using a malicious commit that uses the same abbreviation.

Schritte:
    - verwendet: actions/javascript-action@172239021f7ba04fe7327647b213799853a9eb89

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 die folgenden Informationen in Ihre README.md-Datei aufnehmen:

• eine ausführliche Beschreibung, was die Aktion bewirkt
• erforderliche Eingabe- und Ausgabeargumente
• optionale Eingabe- und Ausgabeargumente
• 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. For more information about building apps, see "About apps."

Stärken von GitHub Aktionen und GitHub Apps

While both GitHub Actions and GitHub Apps provide ways to build automation and workflow tools, they each have strengths that make them useful in different ways.

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 Clone Ihres Repositorys einschließen und dadurch Bereitstellungs- und Veröffentlichungs-Tools, Code-Formatierer und Befehlszeilen-Tools den Zugriff auf Ihren Code erlauben.
• Erfordern weder, dass Du Code noch eine App bereitstellst.
• Verfügen Sie über 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.

Weiterführende Informationen

• „Entwicklungstools für GitHub Actions“