Eigene Actions entwickeln

Eigene Actions entwickeln

0:00 Zum Abschluss des zweiten Tages bauen wir selbst eine Action. Vorweg eine Warnung, die zum ganzen Modul gehört: Eine veröffentlichte Action ist ein Produkt mit Nutzern. Wer sie herausgibt, übernimmt Wartung, Dokumentation und Versionierung — und im Zweifel den Anruf, wenn eine Änderung zwölf fremde Pipelines lahmlegt. Deshalb steht am Anfang jeder Action die Frage, ob es wirklich eine sein muss.

0:22 Wir sehen uns die drei Bauarten an, sprechen über Fehlerverhalten und Diagnose und klären zum Schluss, wie man eine Action veröffentlicht, ohne ihre Nutzer zu überraschen.

Eigene Actions entwickeln

0:33 Letztes Modul des zweiten Tages. Erst die Entscheidung zwischen den Bauarten und der Aufbau der Beschreibungsdatei, dann Verhalten und Fehlerbehandlung, zuletzt die Veröffentlichung. Am Ende existiert die Action beetkarte-version, die aus Manifest und Git-Tag eine Versionsnummer ableitet — mit einem Fehlerfall, den Sie tatsächlich ausgelöst haben.

Actiontypen und die action.yml

0:53 Beginnen wir mit der Entscheidung, die vor der ersten Zeile Code steht: Welche Bauart passt — und braucht es überhaupt eine Action? Jede Action beschreibt sich in einer Beschreibungsdatei: Name, Beschreibung, Eingaben, Ausgaben und die Angabe, wie sie ausgeführt wird. Genau diese letzte Angabe entscheidet die Bauart. Composite bedeutet: eine Folge von Schritten, wie wir sie im letzten Modul gesehen haben.

1:17 Die JavaScript-Variante führt echten Code aus — aktuell auf Node 24. Und die Container-Variante bringt ihre eigene Umgebung mit, läuft aber nur auf Linux und startet langsamer. Die Beschreibung, die Sie hier hinterlegen, ist übrigens das, was Nutzer im Marketplace sehen — sie ist Dokumentation, nicht Formsache. Diese Tabelle liest sich als Empfehlung von oben nach unten: Die einfachste Bauart, die trägt, gewinnt. Ganz oben steht bewusst das Skript im Workflow — also gar keine Action.

1:47 Für Logik, die genau einmal vorkommt, ist das die richtige Antwort. Composite lohnt sich, sobald sich eine Schrittfolge wiederholt. JavaScript brauchen Sie, wenn echte Logik dazukommt: Aufrufe an Schnittstellen, Fehlerbehandlung, Fallunterscheidungen. Und der Container ist die Wahl, wenn ein fremdes Werkzeug in einer festen Umgebung laufen muss — mit den genannten Einschränkungen als Preis.

2:11 Hier sehen Sie eine Schnittstelle im Entwurf. Die Eingabe hat eine Beschreibung und einen sinnvollen Standardwert — damit muss ein Aufruf im Normalfall gar nichts angeben. Das ist gutes Handwerk: Standardwerte sind Freundlichkeit gegenüber den Nutzern. Die Ausgabe ist die Versionsnummer. Wichtig zu wissen: Eingaben erreichen den Code als Umgebungsvariablen mit einem festen Präfix und in Großbuchstaben — das sehen wir gleich im nächsten Codebeispiel.

2:37 Und die Beschreibung sollte erklären, wozu die Action da ist, nicht wie sie intern arbeitet. Der erste Punkt ist der wichtigste des Moduls: eine Action für etwas, das zwei Zeilen Shell gewesen wären. Jede Action, die existiert, muss gepflegt werden — der Aufwand endet nicht mit dem Schreiben. Der zweite ist ein Schnittstellenbruch mit großer Reichweite: Ein umbenannter Eingabename bricht alle Aufrufer.

3:01 Der dritte ist eine kleine Unfreundlichkeit, die sich in jedem Aufruf wiederholt. Und der vierte ist der klassische Dokumentationsfehler — die Beschreibung erklärt die Umsetzung, obwohl Nutzer den Zweck suchen.

Verhalten, Fehler und Diagnose

3:14 Jetzt zum Verhalten. Eine Action wird an ihrer Zuverlässigkeit gemessen, und die zeigt sich nicht im Normalfall, sondern im Fehlerfall. Der Runner versteht genau eine Sprache: den Rückgabewert. Ist er ungleich null, gilt der Schritt als gescheitert — alles andere, auch die schönste Fehlermeldung, ist nur Text. Werte gibt eine Action über dieselbe Ausgabedatei zurück, die wir in Modul vier kennengelernt haben, Meldungen über Workflow Commands.

3:41 Bei der JavaScript-Variante gibt es zusätzlich die Möglichkeit, vor und nach dem Hauptlauf etwas auszuführen — praktisch für Dienste, die gestartet und danach zuverlässig wieder beendet werden müssen. Zwei Dinge passieren hier, und beide sind gleich wichtig. Unten wird der ermittelte Wert in die Ausgabedatei geschrieben — das ist der Normalfall.

4:01 Oben wird geprüft, ob die erwartete Datei überhaupt existiert, und wenn nicht, gibt es eine Fehlermeldung und einen Abbruch. Achten Sie auf den zweiten Teil davon: Ohne den ausdrücklichen Abbruch würde der Schritt trotz Fehlermeldung als erfolgreich gelten. Das ist der häufigste Fehler in selbstgebauten Actions — die Meldung steht im Log, und die Pipeline läuft munter mit leeren Werten weiter.

4:24 Der rote Faden ist: erst im Kleinen, dann für andere. Binden Sie die Action zunächst über einen lokalen Pfad im selben Repository ein — das erspart Ihnen den Zyklus aus Commit, Tag und Aufruf bei jeder Änderung. Dann lösen Sie den Fehlerfall aus und prüfen, ob der Job wirklich rot wird; das ist der Punkt, an dem die meisten Actions durchfallen.

4:44 Danach die unerwarteten Eingaben: leer, falsch geschrieben, mit Sonderzeichen. Und erst wenn das steht, verschieben Sie die Action in ein eigenes Repository. Der erste Punkt ist der eben besprochene fehlende Abbruch — und er ist gefährlich, weil die Pipeline grün bleibt und mit falschen Werten weiterarbeitet. Der zweite ist ein Sicherheitsthema, das wir morgen vertiefen: Eingaben, die ungeprüft in Kommandos wandern, öffnen dieselbe Lücke, über die wir bei Pull-Request-Titeln sprechen werden.

5:12 Der dritte ist eine Frage der Höflichkeit — wenn eine Action ins Arbeitsverzeichnis schreibt, sollte das dokumentiert sein. Und der vierte trifft Actions, die auf einem frischen Runner plötzlich nicht mehr funktionieren.

Veröffentlichen und pflegen

5:25 Zum Schluss die Frage, die aus einem Stück Code ein Produkt macht: Wie geben Sie eine Version heraus, ohne Ihre Nutzer zu überraschen? Versioniert wird über Git-Tags, und üblich sind zwei Sorten gleichzeitig: ein unveränderlicher Tag je Version und ein beweglicher Hauptversions-Tag, der auf die jeweils neueste verträgliche Fassung zeigt.

5:44 Das ist bequem für Nutzer — sie bekommen Korrekturen automatisch — und verlangt vom Autor Disziplin: Auf den beweglichen Tag darf nur, was wirklich verträglich ist. Wer echte Unveränderlichkeit braucht, referenziert den vollständigen Commit. Genau darüber sprechen wir morgen im Sicherheitsmodul ausführlich. Die Wahl hängt vom Schutzbedarf ab. Interne Teams folgen sinnvollerweise dem Hauptversions-Tag und bekommen damit Korrekturen ohne eigenes Zutun.

6:11 Sicherheitskritische Repositories pinnen auf den vollständigen Commit und nehmen dafür in Kauf, dass sie Aktualisierungen selbst nachziehen müssen — meist automatisiert über Dependabot. Der dritte Punkt richtet sich an Sie als Autor: Der bewegliche Tag ist ein Versprechen. Und der vierte ist die Konsequenz daraus: Ein Bruch bekommt eine neue Hauptversion, nie einen stillen Nachzug am alten Tag.

6:34 Vier Schritte, die zusammen eine ordentliche Veröffentlichung ergeben. Erst beschreiben, was sich ändert und was das für Nutzer bedeutet — das ist der Teil, den man gern überspringt und den Nutzer am dringendsten brauchen. Dann der unveränderliche Tag für die konkrete Version. Dann der Hauptversions-Tag, nachgezogen auf denselben Stand.

6:53 Und schließlich ein Release, damit die Änderung sichtbar wird und nicht nur im Git-Verlauf steht. Für interne Actions gilt übrigens: Eine Veröffentlichung im Marketplace ist nicht nötig, ein internes Repository genügt völlig. Der erste Punkt ist der Albtraum jedes Plattformteams: Der Hauptversions-Tag zieht ein brechendes Verhalten nach, und am Montagmorgen stehen fremde Pipelines.

7:15 Der zweite verhindert saubere Versionierung — liegt die Action im Repository der Anwendung, teilt sie sich deren Tags. Der dritte ist der Dokumentationsmangel, der Nutzer zwingt, die Umsetzung zu lesen. Und der vierte ist der organisatorische: Sobald der ursprüngliche Autor das Team verlässt, fühlt sich niemand zuständig — und die Action altert still vor sich hin.

Übung

7:36 In der Übung bauen Sie beetkarte-version — klein genug für eine Stunde, vollständig genug, um alle Themen dieses Moduls zu berühren. Drei Anforderungen, und die mittlere ist die eigentliche. Die Action ermittelt eine Version und gibt sie zurück — das ist Handwerk. Sie beendet den Job bei fehlendem Manifest mit einer Fehlermeldung — und das müssen Sie ausgelöst haben, nicht nur geschrieben.

7:59 Und sie ist unter einem unveränderlichen Tag veröffentlicht. Zur Vertiefung geben Sie eine zweite Fassung heraus und ziehen den Hauptversions-Tag bewusst nach; dann haben Sie den Vorgang einmal gemacht, bevor er im Ernstfall ansteht. Die Schritte folgen der Reihenfolge, in der man eine Action sinnvoll entwickelt: erst die Schnittstelle, dann die Umsetzung, dann das Fehlerverhalten.

8:21 Schritt vier ist der wichtigste — beide Fälle tatsächlich auslösen, den guten und den schlechten. Und erst danach der Umzug in ein eigenes Repository mit Tag. Wer diese Reihenfolge umdreht und zuerst veröffentlicht, verbringt den Nachmittag mit einer langen Kette aus Commit, Tag, Aufruf und Warten — für jede kleine Korrektur.

8:41 Der erste Punkt ist eine Besonderheit der Composite-Bauart, die man leicht übersieht: Die Ausgabe muss in der Beschreibungsdatei ausdrücklich mit dem erzeugenden Schritt verknüpft werden — sonst bleibt sie leer, obwohl der Schritt sie geschrieben hat. Der zweite ist der ungetestete Fehlerfall. Der dritte ist eine Entwurfsfrage, die Sie klären sollten: Wenn Version aus Manifest und Git-Tag kommen kann, welcher gewinnt?

9:04 Und der vierte ist der Flüchtigkeitsfehler beim Veröffentlichen. Morgen geht es dann um Deployments, Sicherheit und Betrieb.