Daten zwischen Schritten und Jobs austauschen

Daten zwischen Schritten und Jobs austauschen

0:00 In den ersten Modulen haben wir Schritte aneinandergereiht. Jetzt sollen sie miteinander reden. Das klingt trivial, ist es aber nicht: Jeder Schritt startet in einer eigenen Shell, und jeder Job auf einer eigenen Maschine. Was weitergegeben werden soll, muss deshalb einen ausdrücklichen Weg nehmen — meist über eine Datei.

0:18 In diesem Modul lernen Sie die Kontexte kennen, aus denen Ihr Workflow seine Informationen bezieht, die Ausgaben, mit denen Schritte und Jobs Werte weiterreichen, und die Workflow Commands, mit denen ein Lauf Annotationen und Zusammenfassungen erzeugt. Es ist das unspektakulärste Modul des Tages — und das, dessen Konzepte Sie danach überall wiedersehen.

Daten zwischen Schritten und Jobs austauschen

0:39 Viertes Modul des ersten Tages. Wir klären zuerst, woher ein Workflow überhaupt seine Werte hat, dann wie Werte von Schritt zu Schritt und von Job zu Job wandern, und schließlich, wie ein Lauf sichtbar macht, was er getan hat. Am Ende reicht die Beetkarte ihre Versionsnummer sauber durch die Pipeline — die brauchen wir in Modul acht für den Image-Tag wieder.

Variablen und Kontexte

0:58 Fangen wir mit der Frage an, woher ein Workflow seine Informationen bezieht — und mit der wichtigsten Unterscheidung dabei: Was darf im Log stehen und was nicht. Kontexte sind Objekte, die GitHub Ihnen zur Laufzeit hinstellt. Stellen Sie sich eine Werkbank vor, auf der schon alles bereitliegt: Informationen zum Lauf und zum auslösenden Ereignis, Ihre eigenen Variablen, die Konfigurationswerte aus Repository oder Organisation und die hinterlegten Geheimnisse.

1:25 Der Unterschied zwischen den letzten beiden ist der wichtigste dieses Kapitels: Konfigurationswerte stehen im Klartext im Log, Geheimnisse werden maskiert. Wer beides verwechselt, hat entweder einen unnötig unsichtbaren Wert oder ein sichtbares Geheimnis — und der zweite Fall lässt sich nicht rückgängig machen. Diese sechs Kontexte decken den Alltag ab. Zwei Hinweise, die Ihnen Suchzeit ersparen. Erstens: Kontexte sind nicht überall verfügbar.

1:51 Auf Workflow-Ebene, also ganz oben in der Datei, stehen nur drei davon bereit — der Rest existiert dort schlicht noch nicht, weil es weder Job noch Schritt gibt. Zweitens: Der Kontext für Ausgaben vorheriger Jobs funktioniert nur, wenn Sie diese Jobs auch als Abhängigkeit eingetragen haben. Sonst ist er leer, ohne Fehlermeldung.

2:11 Das ist einer der häufigsten Gründe, warum eine Wertweitergabe scheinbar grundlos nicht funktioniert. Die Entscheidung fällt an einer einfachen Frage: Würde es schaden, wenn dieser Wert im Log stünde? Ein Registry-Name oder eine Node-Version schadet nicht — die gehören in Variablen, und dann können Sie im Log auch nachsehen, was tatsächlich verwendet wurde.

2:33 Ein Zugangsschlüssel gehört ins Geheimnis. Wichtig dabei: Die Maskierung ist eine Notbremse, kein Schutzkonzept. Sie ersetzt bekannte Zeichenketten im Log — mehr nicht. Bei strukturierten Werten wie JSON greift sie nicht zuverlässig, weil der Wert in Teilen ausgegeben wird. Solche Daten gehören deshalb nie in ein einzelnes Geheimnis.

2:53 Der erste Punkt ist der schmerzhafteste, weil er endgültig ist: Ein Geheimnis in einer Zusammenfassung steht dort dauerhaft, und der Ersatz des Schlüssels ist dann Pflicht, nicht Kür. Der zweite kostet eine Viertelstunde Verwirrung — die Änderung im Repository wirkt nicht, weil der Workflow den anderen Mechanismus verwendet.

3:12 Der dritte betrifft die eben erwähnte Verfügbarkeit von Kontexten. Und der vierte ist heimtückisch: Sie setzen eine Umgebungsvariable, aber das Runner-Image bringt bereits eine gleichnamige mit, die später gewinnt.

Expressions und Outputs

3:24 Jetzt zum eigentlichen Transport. Wie kommt ein Wert, den ein Schritt berechnet hat, in den nächsten Schritt — und wie kommt er über die Grenze zu einem anderen Job? Der Weg führt über eine Datei. Ein Schritt schreibt seinen Wert in eine von GitHub bereitgestellte Ausgabedatei, und damit ihn jemand adressieren kann, braucht er eine Kennung.

3:44 Ein Job wiederum erklärt ausdrücklich, welche seiner Schrittausgaben er nach außen weitergibt — und nachgelagerte Jobs, die ihn als Abhängigkeit führen, können sie lesen. Das wirkt umständlich, hat aber einen guten Grund: Jobs laufen auf verschiedenen Maschinen und teilen nichts, was sie nicht ausdrücklich teilen. Für größere Dateien ist dieser Weg allerdings nicht gedacht — dafür gibt es Artefakte.

4:07 Das Muster, das Sie hier sehen, werden Sie ständig brauchen. Ein Schritt ermittelt einen Wert — hier die Versionsnummer aus der Manifestdatei der Beetkarte — und schreibt ihn in die Ausgabedatei. Der Job erklärt diesen Wert dann zu seiner eigenen Ausgabe. Zwei Punkte, auf die es ankommt: Der Schritt braucht eine Kennung, sonst gibt es nichts zu referenzieren, und der Job muss die Ausgabe ausdrücklich deklarieren.

4:32 Und beachten Sie die Größenordnung: Ausgaben sind auf ein Megabyte je Job begrenzt. Alles Größere ist ein Artefakt, kein Wert. Vier Transportwege, und die Wahl fällt nach der Art der Fracht. Einzelne Werte wie Version, Digest oder Image-Tag gehen als Ausgabe. Dateien, die ein späterer Job unverändert braucht, gehen als Artefakt — das behandeln wir in Modul sechs ausführlich.

4:55 Und jetzt der wichtigste Punkt: Ein Cache ist kein Transportweg. Er darf jederzeit fehlen, ohne dass etwas kaputtgeht — das ist seine definierende Eigenschaft. Wer einen Cache als Übergabe missbraucht, baut eine Pipeline, die meistens funktioniert. Meistens ist in der Automatisierung das schlechteste aller Ergebnisse. Die ersten beiden Punkte erklären zusammen fast jeden Fall von „der Wert kommt nicht an": entweder fehlt die Kennung am Schritt, oder die Abhängigkeit zwischen den Jobs.

5:25 Der dritte betrifft mehrzeilige Werte — die brauchen eine besondere Schreibweise mit Begrenzern, sonst zerreißen sie die Ausgabedatei und nehmen andere Werte mit. Und der vierte ist die Notlösung, die man immer wieder sieht: Der Wert wird ins Log geschrieben und später aus dem Log zurückgelesen. Das funktioniert, bis jemand eine Zeile Ausgabe ergänzt.

Workflow Commands und Diagnose

5:45 Zum Schluss die andere Richtung: Wie spricht ein Lauf mit uns? Über besonders formatierte Ausgaben, die der Runner auswertet — und die überraschend viel können. Workflow Commands sind Ausgaben in einem bestimmten Format, die der Runner nicht als Text, sondern als Anweisung liest. Damit setzen Sie Annotationen, die im Pull Request an der betroffenen Codezeile erscheinen, maskieren Werte nachträglich, gruppieren lange Logausgaben und schreiben eine Zusammenfassung, die über der Ansicht des Laufs steht.

6:14 Gerade Letzteres wird selten genutzt und ist enorm nützlich: Statt dass jemand ein Log durchsucht, steht das Ergebnis lesbar oben — die Zahl der Tests, die Coverage, der ausgerollte Stand. Drei Beispiele, drei verschiedene Zwecke. Die Annotation mit Datei und Zeile ist der Unterschied zwischen „irgendwo im Log steht ein Fehler" und einer Markierung direkt an der Stelle im Pull Request.

6:36 Die Maskierung sorgt dafür, dass ein Wert im weiteren Log ersetzt wird — nur eben erst ab dem Moment, in dem Sie sie setzen. Und die letzten beiden Zeilen schreiben in die Zusammenfassung, in gewöhnlichem Markdown. Denken Sie beim Schreiben daran, dass angehängt und nicht überschrieben wird — sonst bleibt nur die letzte Zeile übrig.

6:55 Ausdrücke scheitern selten mit einer klaren Meldung; meistens sind sie einfach leer. Der rote Faden dieser vier Schritte ist deshalb: sichtbar machen, bevor man rät. Erst den Ausdruck isoliert ausgeben. Dann prüfen, ob der Kontext an dieser Stelle überhaupt existiert — das ist die häufigste Ursache. Dann auf Datentypen achten, denn eine leere Zeichenkette, ein Nullwert und ein Falsch verhalten sich in Bedingungen verschieden.

7:21 Und wenn gar nichts hilft, das ausführliche Protokoll einschalten. Eine Warnung dazu: Bevor Sie irgendetwas ausgeben, prüfen Sie, ob ein Geheimnis darin stecken könnte. Der erste Punkt ist eine Nebenwirkung des nächsten Moduls: Wenn eine Matrix zwanzig Jobs erzeugt und jeder eine Zusammenfassung schreibt, entsteht ein unlesbarer Stapel.

7:41 Der zweite ist der Klassiker bei der Maskierung — sie wirkt erst ab dem Zeitpunkt, an dem sie gesetzt wird, und schützt nicht rückwirkend. Der dritte ist harmlos, aber ärgerlich beim Lesen. Und der vierte ist ein echtes Risiko: Das ausführliche Protokoll bleibt eingeschaltet, weil es beim Suchen half, und schreibt seitdem Werte mit, die niemand sehen sollte.

Übung

8:02 Jetzt bringen wir das zusammen: Die Beetkarte soll ihre Versionsnummer einmal ermitteln und durch die ganze Pipeline tragen — statt sie an drei Stellen neu zu erraten. Die Aufgabe hat einen praktischen Kern und einen konzeptionellen. Praktisch: Die Version wird einmal gelesen, als Job-Ausgabe weitergereicht und im Folgejob für den Image-Tag verwendet.

8:22 Konzeptionell: Sie sollen begründen können, warum es eine Ausgabe ist und kein Artefakt und kein Cache. Dazu kommt die Zusammenfassung mit dem Testergebnis — damit man das Ergebnis sieht, ohne ein Log zu öffnen. Und zur Vertiefung eine Annotation, die im Pull Request an der richtigen Zeile landet. Das ist die Art von Detail, die ein Team spürbar entlastet.

8:44 Die ersten drei Schritte sind die Kette, die wir eben besprochen haben: lesen, als Ausgabe deklarieren, im Folgejob über die Abhängigkeit verwenden. Wenn dabei etwas leer bleibt, prüfen Sie genau diese drei Stellen in dieser Reihenfolge. Schritt vier ist die Zusammenfassung, und Schritt fünf ist der, den man gern überspringt: einmal kontrollieren, dass in Log und Zusammenfassung kein Geheimnis gelandet ist.

9:07 Machen Sie sich das zur Gewohnheit — es ist deutlich angenehmer als der Austausch eines kompromittierten Schlüssels. Die ersten beiden Punkte kennen Sie inzwischen — sie sind die häufigsten Ursachen und lassen sich in zwei Minuten prüfen. Der dritte ist ein Formatierungsproblem, das beim Anhängen an die Zusammenfassung entsteht.

9:25 Und der vierte ist der inhaltlich interessanteste: Wenn die Version an zwei Stellen unabhängig ermittelt wird, laufen Build und Deployment irgendwann auseinander — und niemand merkt es, bis ein Image den falschen Tag trägt. Genau deshalb reicht man Werte durch, statt sie zu wiederholen. Im nächsten Modul wird die Pipeline dann schnell.