TOML in YAML umwandeln

Viele deutsche Teams betreiben GitLab selbst, aus genau dem Grund, aus dem hier überhaupt jemand landet: Der Quellcode und die Baupläne dafür sollen nicht auf einem amerikanischen Server liegen, sondern auf einer Instanz, die die eigene IT-Abteilung verwaltet, oft mit einer eigenen Datenschutz-Folgenabschätzung im Aktenordner. Die Pipeline-Definition dafür ist trotzdem YAML, während die Fakten über das Projekt — Paketname, unterstützte Python- oder Rust-Version, Abhängigkeiten, Feature-Flags — in einer pyproject.toml oder Cargo.toml stehen. Niemand hat sich diese Aufteilung ausgesucht; zwei Ökosysteme haben sie unabhängig voneinander getroffen.

Diese Aufgabe ist deshalb selten eine Migration, sondern eine Abschrift: die Werte korrekt in YAML-Syntax bringen und dann genau das in die .gitlab-ci.yml übernehmen, was die Matrix oder die Variablen wirklich brauchen. Das Ergebnis muss keine fertige Pipeline sein — es muss eine Vorlage sein, aus der man ohne Tippfehler abschreiben kann. Wer stattdessen versucht, die ganze Ausgabe unverändert als Pipeline-Datei einzuchecken, merkt spätestens beim ersten Lauf, dass eine Cargo.toml und eine .gitlab-ci.yml unterschiedliche Pflichtfelder haben — die eine beschreibt ein Paket, die andere beschreibt Jobs, Stages und Runner-Tags, und keine Umwandlung kann das eine in das andere überführen.

TOML kennt echte Datumswerte ohne Anführungszeichen: `launch = 2026-03-01T08:00:00Z`. In der YAML-Datei landet dieselbe Angabe genauso unquotiert — `launch: 2026-03-01T08:00:00.000Z` —, denn das ist die Form, die YAML für einen Zeitstempel reserviert. Eine Umwandlung nach JSON würde denselben Wert in Anführungszeichen setzen, weil JSON nur einen Skalartyp für Text kennt und sonst nichts anzubieten hat. Das macht YAML an dieser einen Stelle näher am Original als der vermeintlich neutralere JSON-Weg.

Was die fehlenden Anführungszeichen tatsächlich bewirken, entscheidet der Reader, der die Datei später lädt, nicht die Datei selbst. Wird das Ergebnis mit derselben Bibliothek gelesen, die es geschrieben hat — nach dem YAML-1.2-Kernschema —, kommt eine Zeichenkette zurück, weil 1.2 keinen Zeitstempel-Resolver kennt. Ein Loader nach YAML 1.1, wie PyYAML oder Rubys Psych ihn noch verwenden, typisiert dieselbe Zeile tatsächlich als Datum — und tut das lückenhaft: eine reine Uhrzeit ohne Datum wie `at: 08:00:00.000` wird dabei zur Zahl 28800 statt zu einer Uhrzeit, und eine Zeitzone wird beim Einlesen still auf UTC normiert. Wer sich auf ein Datum als Datum verlassen muss, sollte das am Zielort erzwingen, nicht der Form der Datei vertrauen.

Ein `[package]`-Kopf wird zu einem obersten Schlüssel mit den Werten darunter eingerückt. Ein `[tool.black]`-Kopf wird zu `tool:`, darin `black:`, darin die Einstellungen — weil eine gepunktete Tabellenüberschrift eine Verschachtelung ist und kein Name mit Punkten drin. Gepunktete Schlüssel verhalten sich identisch: `a.b = 1` wird zu `a:` mit `b: 1` darunter, und dasselbe gilt für drei oder vier Ebenen tiefe Pfade, wie sie in einer pyproject.toml unter `[tool.poetry.group.dev.dependencies]` durchaus vorkommen.

Die Reihenfolge bleibt die der Quelldatei, weil TOML lose Werte am Anfang der Datei ohnehin vor die erste Tabellenüberschrift zwingt. Was sich verschiebt, sind über die Datei verstreute gepunktete Schlüssel — die landen im YAML gesammelt unter einem gemeinsamen Elternschlüssel, was lesbarer ist, aber nicht mehr aussieht wie die Quelle. Wer die TOML-Datei kennt und im Diff nach der gewohnten Reihenfolge sucht, findet sie an dieser einen Stelle nicht wieder, und wer die YAML-Datei stattdessen zuerst liest, bekommt tatsächlich eine übersichtlichere Gruppierung als das Original.

Das ist der eigentliche Bruch, und er fällt kaum auf, weil die Ausgabe so ähnlich aussieht. In TOML ist `enabled = true` ein Boolean, weil die Syntax es so sagt, und `version = "1.0"` ein Text, weil er in Anführungszeichen steht. Nichts wird erraten. In YAML ist ein unquotierter Wert das, wofür der jeweilige Parser ihn hält — deshalb setzt der Schreiber hier vorsorglich Anführungszeichen.

Er tut das dort, wo es zählt: eine Ziffernfolge kommt in Anführungszeichen heraus, damit `version = "1.0"` als `version: "1.0"` bestehen bleibt und nicht als Zahl 1. Nicht in Anführungszeichen stehen dagegen `NO`, `yes`, `on` und `off`, weil das unter YAML 1.2 gewöhnliche Zeichenketten sind und die Datei für einen 1.2-Parser geschrieben ist. Lädt eine .gitlab-ci.yml das über eine Variable mit einem älteren YAML-1.1-Loader, werden aus diesen Wörtern plötzlich Booleans — ein Fall, an den in TOML nie zu denken war, weil die Sprache dafür gar keine unquotierten Wörter zulässt.

Ein wiederholter `[[bin]]`- oder `[[tool.poetry.packages]]`-Block ist TOMLs Form für eine Liste von Datensätzen, und er wird zu genau der Form, die in YAML überall von Hand geschrieben wird: ein Strich pro Eintrag, die Schlüssel darunter eingerückt. Einfache Arrays folgen demselben Muster, eine Zeile mit Strich pro Element, auch wenn sie in der TOML-Datei kompakt in einer Zeile standen.

Diese Blockform ist das, was die meisten YAML-Werkzeuge dokumentieren, also lässt sich ein Eintrag meist ohne Nacharbeit in eine Pipeline-Variable oder eine values.yaml übernehmen. Will die Zieldatei ausdrücklich Flow-Notation — eine Matrixzeile als `[3.11, 3.12, 3.13]`, wie sie in einer GitHub-Actions- oder GitLab-Matrix oft kompakter wirkt —, bleibt das eine kleine, aber manuelle Nacharbeit.

Ein dreifach zitierter TOML-Text mit einem Skript, einer Beschreibung oder einem Lizenztext behält seine Zeilenstruktur. Der Schreiber gibt ihn als Blockskalar aus — der Schlüssel, ein Strich, darunter die eigentlichen Zeilen eingerückt — statt als eine einzelne Zeile mit Escape-Zeichen, was bei einem mehrzeiligen Shell-Snippet in einem `[tool]`-Block den Unterschied zwischen lesbar und unlesbar macht.

Eine lange, aber einzeilige Zeichenkette wird dagegen bei etwa achtzig Spalten umgebrochen, und YAML liest diese Umbrüche beim Laden wieder als Leerzeichen, sodass der Wert unverändert bleibt. Eine lange URL kann dadurch im Editor über zwei Zeilen verteilt erscheinen — irritierend, aber nicht beschädigt, und im Zweifel liest man den Wert aus der geladenen Struktur und nicht aus dem rohen Text.

TOML und YAML unterstützen beide `#`-Kommentare, und eine Cargo.toml oder pyproject.toml ist meist voll davon: warum eine Abhängigkeit auf eine Patch-Version fixiert ist, welche von zwei Einstellungen absichtlich so steht, welcher Kollege eine Ausnahme eingetragen hat und warum. Nichts davon übersteht die Umwandlung, weil der Reader Kommentare beim Einlesen verwirft und der Schreiber keine platziert.

Für einen Ausschnitt, den man kurz in eine Pipeline-Variable einfügt, ist das unbedeutend. Für alles, was dauerhaft gepflegt werden soll, ist es der Grund, warum die TOML-Datei die eigentliche Quelle bleibt und die YAML-Datei generiert wird — zwei Dateien mit denselben Werten und nur eine mit der Begründung dahinter ist ein Problem für den, der das Projekt irgendwann übernimmt. Muss die YAML-Datei doch eingecheckt werden, lohnt sich eine einzige handgeschriebene Kopfzeile, die sagt, aus welcher Manifest-Datei sie stammt.

Die Ausgabe nutzt eine schlichte Teilmenge der Sprache. Es gibt keine Anker und keine Aliase — eine wiederholte Unter-Tabelle steht zweimal vollständig statt einmal mit Referenz, weil die geparsten Werte separate Objekte sind und nichts sie zusammenführt. Es gibt kein null, weil TOML keins kennt, keine Tags, keine expliziten Typen und keine Dokumenttrenner.

Erwartet die .gitlab-ci.yml an anderer Stelle solche Konstrukte — etwa Anker, um eine Vorlage für mehrere Jobs zu teilen, oder Tags für einen Vault-verschlüsselten Wert in einem Ansible-Playbook —, muss man sie von Hand ergänzen. Das ist keine Schwäche der Umwandlung, sondern die Konsequenz daraus, dass die Manifest-Datei diese Dinge nie ausgedrückt hat.

TOML verbietet eine führende Null bei einer echten Ganzzahl — `port = 0443` ist ein Syntaxfehler, keine gültige Portnummer. Wer einen Wert mit führender Null tatsächlich braucht, etwa eine Postleitzahl oder ein Versionssegment, muss ihn in der Manifest-Datei schon als Zeichenkette in Anführungszeichen schreiben, `port = "0443"`.

Das ist keine Einschränkung, die die Umwandlung einführt, sondern eine, die die Quelldatei bereits mitbringt: Steht der Wert dort als Text, kommt er auch in der YAML-Datei als quotierter Text an, mit den Nullen intakt. Steht er versehentlich als Zahl in der TOML-Datei, war die führende Null schon vor der Umwandlung verloren, und keine Umwandlung kann sie zurückholen.

Der günstigste Test ist ein Rücklauf. Die Ausgabe mit demselben Werkzeug laden, das sie später tatsächlich verarbeitet, und ein paar Werte gegen die TOML-Datei vergleichen: die Versionsnummer, ein Datum, alles, was wie eine Zahl aussieht und eigentlich Text sein soll, und jeden bloßen Wortwert wie `yes` oder `on`. Wer die Datei in mehreren Systemen weiterverwendet — etwa dieselbe values.yaml sowohl lokal mit Helm als auch später in einer GitLab-Pipeline mit einem anderen YAML-Loader —, prüft am besten in beiden, weil genau der Unterschied zwischen 1.1 und 1.2 der Teil ist, den man sonst erst im laufenden Betrieb bemerkt.

Ein `yq eval . out.yaml` formatiert neu und meldet einen Syntaxfehler, falls einer vorliegt. Ein `python -c "import yaml, sys; print(yaml.safe_load(open('out.yaml')))"` zeigt, was ein YAML-1.1-Loader aus der Datei macht — die Version der Wahrheit, die zählt, wenn das Ziel Ansible oder ein älteres Kubernetes-Werkzeug ist. Das einmal zu prüfen ist schneller, als eine fehlgeschlagene Pipeline zu debuggen, weil irgendwo `version: 1` stand, wo `"1.0"` gemeint war.

GitLab liest eine `.gitlab-ci.yml` von oben nach unten für `stages`, während `variables` und Job-Definitionen an beliebiger Stelle stehen dürfen. Die aus TOML erzeugte YAML-Ausgabe folgt dagegen strikt der Reihenfolge der Quelldatei, weil nichts umsortiert wird — ein `[tool.poetry]`-Block, der in der Cargo- oder pyproject-Datei weit unten steht, landet auch in der YAML-Ausgabe weit unten.

Für eine Pipeline-Datei, die Lesbarkeit von oben nach unten erwartet, lohnt es sich deshalb, die übernommenen Werte an die passende Stelle in der Zieldatei zu ziehen, statt den ganzen generierten Block unverändert einzufügen. Das ist Handarbeit von wenigen Minuten und der Grund, warum die Ausgabe hier als Fundgrube gedacht ist und nicht als fertiger Abschnitt zum Hineinkopieren.

In diesem Browser-Tab, mit reinem JavaScript. Es wird nichts hochgeladen, es gibt keine Warteschlange, kein Konto und kein Tageskontingent. Wer das nicht glauben will, öffnet vor dem Ablegen der Datei den Netzwerk-Tab der Entwicklertools und wandelt einmal um — die Bestätigung steht dort und nicht in diesem Absatz.

Ein Manifest ist selten groß genug, um an die 100-MB-Obergrenze für Browser-Umwandlungen auch nur heranzukommen, aber es ist nicht immer öffentlich. Die Abhängigkeitsliste eines privaten Repositories nennt interne Pakete und interne Registries, und ein `[tool]`-Block trägt manchmal Hostnamen oder Pfade, die mehr über eine Organisation verraten, als beabsichtigt ist. Lokal umzuwandeln bedeutet, dass nichts davon eine Weitergabe ist, und es bedeutet auch, dass sich hundert solcher Dateien aus einem Monorepo in einem Rutsch ablegen lassen, ohne dass irgendeine Warteschlange entsteht — jede läuft für sich im selben Tab.