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 Variablenverweis):
- Verwende für die REST-API die Umgebungsvariable
GITHUB_API_URL. - Verwende für GraphQL die Umgebungsvariable
GITHUB_GRAPHQL_URL.
- Verwende für die REST-API die Umgebungsvariable
-
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 finden Sie unter Veröffentlichungen in einem Repository verwalten.
- Verschieben Sie 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