Veröffentlichen einer benutzerdefinierten GitHub-Aktion

  • 6 Minuten

Hier erfahren Sie mehr über die Auswahl der richtigen Sichtbarkeit für Ihre Aktion, bewährte Methoden zum Dokumentieren und Versionieren Ihrer Aktion und darüber, wie Sie Ihre Aktion im GitHub Marketplace veröffentlichen.

Auswählen eines Speicherorts für Ihre Aktion

Diagramm, das die beiden Sichtbarkeitsoptionen für eine Aktion anzeigt: öffentlich oder privat.

Beim Erstellen einer Aktion ist es wichtig müssen Sie zuerst entscheiden, wo sich diese Aktion befinden und welche Sichtbarkeit sie aufweisen soll, d. h. ob sie public oder private sein soll. Die Sichtbarkeit der Aktion bestimmt, welche Empfehlungen und Anforderungen zum Veröffentlichen dieser Aktion benötigt werden. Betrachten wir diese beiden Sichtbarkeitsoptionen nun genauer.

Öffentlich

Workflows in allen Repository können öffentliche Aktionen verwenden. Wenn Sie eine Aktion mit der Absicht entwickeln, diese als Open Source oder über den GitHub-Marketplace öffentlich verfügbar zu machen, wird empfohlen und in den meisten Fällen sogar gefordert, dass die Aktion über ein eigenes Repository verfügt und nicht mit anderem Anwendungscode gebündelt wird. Dadurch können Sie die Aktion wie jede andere Software versionieren, nachverfolgen und veröffentlichen. Dies erleichtert es der GitHub-Community, die Aktion zu entdecken, schränkt den Bereich der Codebasis auf Entwickler ein, die Probleme beheben und die Aktion erweitern, und trennt die Versionsverwaltung der Aktion von der Versionsverwaltung von sonstigem Anwendungscode ab.

Privat

Wenn sich eine Aktion in einem privaten Repository befindet, kann sie nur von Workflows im gleichen Repository verwendet werden. Bei privaten Aktionen können Sie die Dateien der Aktion an einem beliebigen Speicherort in Ihrem Repository speichern. Wenn Sie Aktions-, Workflow- und Anwendungscode in einem einzigen Repository kombinieren möchten, wird empfohlen, die Aktion im .github-Verzeichnis zu speichern. Beispiel: .github/actions/action-a und .github/actions/action-b.

Dokumentieren Ihrer Aktion

Es kann sehr frustrierend sein, ein neues Tool oder eine neue Anwendung zu verwenden, wenn die Dokumentation ungenau oder gar nicht erst vorhanden ist. Es ist wichtig, eine gute Dokumentation Ihrer Aktion bereitzustellen, damit andere Benutzer*innen die Funktionsweise verstehen können – unabhängig davon, ob Sie diese öffentlich verfügbar machen oder privat halten möchten. Als Erstes erstellen Sie eine gute README.md Datei für Ihre Aktion.

Die README.md-Datei ist häufig der erste Anlaufpunkt für Entwickler, die verstehen möchten, wie die Aktion funktioniert. Diese Datei eignet sich hervorragend für die Angabe aller wichtigen Informationen über die Aktion. Im Folgenden finden Sie eine nicht vollständige Liste von Informationen, die dort angegeben sein sollten:

  • Eine ausführliche Beschreibung, wozu die Aktion dient
  • Erforderliche Eingabe- und Ausgabeargumente
  • Optionale Eingabe- und Ausgabeargumente
  • Geheimnisse, die von der Aktion verwendet werden
  • Umgebungsvariablen, die von der Aktion verwendet werden
  • Ein Beispiel für die Verwendung Ihrer Aktion in einem Workflow

In der Regel sollte die README.md-Datei alle Informationen enthalten, die ein Benutzer benötigt, um die Aktion verwenden zu können. Wenn Sie der Meinung sind, dass es sich um nützliche Informationen handelt, fügen Sie diese in die README.md-Datei ein.

Veröffentlichen und Versionieren Ihrer Aktion

Wenn Sie eine Aktion für andere Personen entwickeln, sollten Sie eine Releaseverwaltungsstrategie definieren, um das Verteilen von Updates zu steuern. Dabei ist unerheblich, ob es sich um eine öffentliche oder eine private Aktion handelt. Hauptversionsupdates, einschließlich notwendiger kritischer Korrekturen und Sicherheitspatches, die sich auf die Kompatibilität auswirken, müssen eindeutig dokumentiert werden.

Bewährte Methoden für die Release- und Versionsverwaltung

Eine gute Releaseverwaltungsstrategie sollte Empfehlungen zur Versionsverwaltung enthalten. Benutzer sollten nicht auf die Standardverzweigung einer Aktion mit der Aktion verweisen. Dies liegt daran, dass die Standardverzweigung, die wahrscheinlich den neuesten Code enthält (der möglicherweise stabil ist) zu einem Workflowbruch führen kann. Stattdessen wird empfohlen, dass Benutzer bei Verwendung der Aktion eine Hauptversion angeben und nur an eine spezifischere Version weitergeleitet werden, wenn Probleme auftreten. Dies kann erreicht werden, indem der GitHub Actions-Workflow mit einem Tag, dem SHA eines Commits oder einem für ein Release benannten bestimmten Branch als Ziel konfiguriert wird. Betrachten wir diese Releaseoptionen nun genauer.

Stichwörter

Tags können eine gute Möglichkeit zum Verwalten von Releases für eine Aktion sein. Durch die Verwendung von Tags können Benutzer leicht zwischen Haupt- und Nebenversionen unterscheiden. Im Folgenden finden Sie eine Liste hilfreicher Methoden, die beim Erstellen von Releases berücksichtigt werden sollten:

  • Erstellen und überprüfen Sie ein Release in einem Releasebranch (z. B. release/v1 ), bevor Sie das Versionstag (z. B. v1.0.2) erstellen.
  • Verwenden Sie die semantische Versionsverwaltung.
  • Verschieben Sie das Hauptversionstag (z. B. v1, v2) so, dass es auf die Git-Referenz der aktuellen Version zeigt.
  • Führen Sie ein neues Hauptversionstag (v2) für Änderungen ein, die vorhandene Workflows unterbrechen.
  • Veröffentlichen Sie Hauptversionen mit einem Betatag, um ihren Status anzugeben, z. B. v2-beta. Sie können das -beta-Tag entfernen, wenn das Release bereit ist.

Im Folgenden finden Sie einige Beispiele für jede Option.

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

Verwenden des SHA-Werts eines Commits

Tags sind nützlich und weit verbreitet. Ein Nachteil bei ihrer Verwendung besteht jedoch darin, dass sie gelöscht oder verschoben werden können. Bei Git erhält jeder Commit einen berechneten SHA-Wert, der eindeutig ist und nicht geändert werden kann. Die Verwendung des SHA-Werts eines Commits für die Versionsverwaltung stellt für Sie die zuverlässigste und sicherste Möglichkeit dar, eine Aktion zu versionieren und zu verwenden. In Git können Sie den SHA-Hash jedoch häufig mit den ersten Zeichen abkürzen, und Git erkennt den Verweis. Wenn Sie den SHA des Commits für die Releaseverwaltung verwenden, müssen Sie den vollständigen SHA-Wert und nicht den abgekürzten Wert verwenden.

steps:
    - uses: actions/javascript-action@2522385f6f7ba04fe7327647b213799853a8f55c

Veröffentlichen einer Aktion im GitHub Marketplace

Rendering, das den GitHub Marketplace umfasst – Tools, um Ihren Workflow zu erstellen und zu verbessern.

Wenn Sie bereit sind, Ihre Aktion mit der GitHub-Community zu teilen, können Sie sie im GitHub Marketplace veröffentlichen und Millionen von GitHub-Benutzer erreichen. Im GitHub Marketplace veröffentlichte Aktionen werden sofort veröffentlicht, sobald alle Anforderungen erfüllt sind. Aktionen, die die Anforderungen nicht erfüllen, müssen vor dem Veröffentlichen von GitHub überprüft werden. Sie müssen sicherstellen, dass das Repository nur die Metadatendatei, den Code und die Dateien enthält, die für die Aktion erforderlich sind. Wenn du ein einzelnes Repository für die Aktion erstellst, kannst du den Code in einer einzelnen Einheit markieren, veröffentlichen und packen. GitHub verwendet die Metadaten der Aktion auch auf Ihrer GitHub Marketplace-Seite.

Im Folgenden finden Sie die Anforderungen zum Veröffentlichen einer Aktion auf dem GitHub-Marketplace. Diese gelten sowohl für auf Docker-Container basierende Aktionen als auch für JavaScript-basierte Aktionen:

  • Die Aktion muss sich in einem öffentlichen Repository befinden.
  • Jedes Repository muss eine einzelne Aktion enthalten.
  • Die Metadatendatei der Aktion (action.yml oder action.yaml) muss sich im Stammverzeichnis des Repositorys befinden.
  • Der Name (name) in der Metadatendatei der Aktion muss im GitHub Marketplace eindeutig sein.
    • Der Name darf nicht mit Benutzer*innen oder einer Organisation auf GitHub übereinstimmen, es sei denn, die Benutzer*innen oder der Organisationsbesitzer veröffentlichen die Aktion. Beispielsweise kann nur die GitHub-Organisation eine Aktion mit dem Namen github veröffentlichen.
    • Der name darf nicht mit einer vorhandenen Kategorie des GitHub-Marketplace übereinstimmen.
    • Der name darf nicht mit einem vorhandenen Feature des GitHub-Marketplace übereinstimmen.

Sie können die erstellte Aktion dem GitHub Marketplace hinzufügen, indem Sie sie als neues Release markieren und anschließend veröffentlichen. In GitHub finden Sie eine Anleitung, mit deren Hilfe Sie einen Release Ihrer Aktion veröffentlichen können. Weitere Informationen zu dieser Anleitung finden Sie im Abschnitt Zusammenfassung am Ende dieses Moduls.