n8n-Workflows sichern und dokumentieren: die Doku liest die KI, nicht ich

Warum GitHub und nicht OneDrive

Der Anlass war unspektakulär: Ich wollte die Workflows automatisch gesichert haben und versionieren können. Wenn auf dem Server etwas in die Hose geht, ist ein Backup besser als keins. Vorher lief das über OneDrive, und das habe ich als ungeeignet empfunden.

Der Grund ist kein Geschmacksurteil. Ein n8n-Workflow ist eine JSON-Datei mit Nodes, Parametern und Verbindungen: Code. Bei OneDrive habe ich davon die jeweils letzte Fassung. Bei GitHub sehe ich, was sich verändert hat, wann und in welchem Node. Und ich habe einen Überblick über den ganzen Bestand, den mir ein Ordner nicht gibt.

Workflows sind Code. Also gehören sie dorthin, wo Code hingehört.

Der Zusatz mit der Dokumentation kam aus demselben Gedanken: Wenn die Sicherung ohnehin automatisch läuft, muss ich auch die Erklärung nicht von Hand schreiben. In einem halben Jahr verstehe ich einen Workflow von 30 Nodes nicht mehr aus dem Stand, selbst wenn ich mir damals Notizen hineingeschrieben habe.

Was jede Nacht passiert

Der Sicherungs-Workflow läuft um 03:00 und hat 20 Nodes. Der aufwendigste Teil ist nicht das Schreiben, sondern die Frage, ob geschrieben werden muss. Denn n8n fasst bei jedem Speichern Felder an, die fachlich nichts bedeuten: updatedAt, versionId, triggerCount, meta. Ohne Gegenmaßnahme hätte ich jede Nacht Diffs ohne inhaltliche Änderung.

Deshalb wird jede Datei erst normalisiert: die flüchtigen Felder fliegen raus, die Schlüssel werden sortiert. Danach entscheidet eine zweistufige Prüfung:

• Stufe 1, Vorfilter: Der updatedAt-Zeitstempel jedes Workflows wird gegen den letzten Sync verglichen. Nur Kandidaten laufen weiter. Bei rund 100 Workflows spart das fast alle GitHub-Aufrufe.
• Stufe 2, Hashvergleich: Für die Kandidaten wird ein Git-Blob angelegt. GitHub gibt den Inhalts-Hash zurück, und identischer Inhalt ergibt dieselbe Prüfsumme, also kein neues Objekt. Diese Prüfsumme wird gegen den Repository-Baum verglichen. Kein Download des Inhalts nötig.

Erst wenn beide Stufen etwas finden, entstehen Blob, Tree, Commit und die Aktualisierung der Referenz. Die Commit-Nachrichten sehen deshalb so aus: n8n sync: 1 geändert. Ändert sich nichts, endet der Zweig ohne Commit.

Zusätzlich schreibt der Lauf eine INDEX.md neu: eine Tabelle aller Workflows mit Status, Trigger, angebundenen Systemen und Node-Anzahl. Aktuell stehen dort 99 Einträge, die archivierten ausgenommen.

Die Doku läuft montags, und sie ist nicht für mich

Der zweite Workflow läuft montags um 04:00, eine Stunde nach dem Backup. Er prüft, für welche Workflows sich die Datei seit der letzten Dokumentation geändert hat, und ruft nur für diese ein Modell auf. Herauskommt pro Workflow ein Markdown im Ordner docs.

Auf die Frage, ob ich diese Dateien lese, ist meine ehrliche Antwort: nein. Ich schaue hinein, wenn mir eine entscheidende Information fehlt oder ich etwas über einen Workflow wissen will. Der eigentliche Zweck ist ein anderer. Wenn ich später etwas suche, kann die KI diese Dokumentation nutzen, um sich im Ordner zu bewegen und zu finden, was ich meine. Sie muss dafür nicht 111 JSON-Dateien lesen, sondern zehn Beschreibungen.

Das ist der Punkt, an dem die Sache für mich interessant wurde: Es ist Dokumentation ohne menschliches Publikum. Geschrieben von einem Modell, gelesen von einem Modell, und ich stehe daneben und profitiere davon, dass die Suche schneller trifft.

Passend dazu eine Kleinigkeit, die ich nicht geplant hatte. In der Übersichtstabelle gibt es eine Spalte Zweck, die für Handarbeit gedacht ist. Die hat sich das Modell selbst ausgedacht, nicht ich. Bei allen Einträgen ist sie leer, und ich brauche sie nicht zwangsläufig. Nützlich wäre sie höchstens bei Workflows, die eigentlich als Sub-Workflows gedacht sind: da sagt der Name allein nicht, wozu sie gehören.

Die Grenze bei 25 Nodes

Dokumentiert wird nicht alles. Zwei Bedingungen filtern:

• Mehr als 25 Nodes. Ab dieser Größe erklären sich Workflows nicht mehr selbst, und dort greift die Dokumentation. Kleinere brauchen sie nicht. Die Schwelle ist Bauchgefühl, und ich schließe nicht aus, dass ich sie noch ändere.
• Nur aktive. Inaktive will ich nicht dokumentiert haben, sie spielen offenbar gerade keine Rolle. Archivierte sind ebenfalls inaktiv, aber eher wie im Papierkorb, und für die will ich kein Geld für Token verschwenden.

Von rund 100 Workflows bleiben dadurch zehn übrig. Das ist eine Entscheidung gegen Vollständigkeit, und sie ist dieselbe wie bei meinen MCP-Servern: Ich richte nur ein, was ich brauche. Ob ich mich bei den inaktiven umentscheide, lasse ich offen.

Was das Modell nicht sehen darf

Ein Repository mit Workflow-Dateien enthält mehr, als man denkt: Hostnamen, Pfade, Endpunkte, interne Adressen. Das Repository ist deshalb privat, und das ist keine Formalie.

Beim Sichern läuft trotzdem eine Redaktion. Muster für Klartext-Geheimnisse werden ersetzt: Bearer-Header, Tokens im Stil bekannter Anbieter, JWTs, generische Präfix-Tokens. Dazu Parameternamen, deren Wert grundsätzlich verdächtig ist, von password bis client_secret.

Ersetzt wird nicht durch einen festen Platzhalter, sondern durch einen kurzen Fingerprint des Werts. Der ist nicht kryptografisch und soll auch nichts schützen: Er soll erkennbar machen, dass sich ein Geheimnis geändert hat, ohne es zu verraten. Bliebe dort ein starrer Platzhalter, wäre ein Wechsel unsichtbar. Stünde der Wert dort, wäre er im Repository.

Und ein Detail, das mir wichtiger ist als die Muster: Das Modell bekommt die Datei aus dem Repository, nicht aus n8n. Also die schon redigierte Fassung. Klartext-Geheimnisse verlassen meine Infrastruktur nicht.

Warum die Prosa über GPT läuft und nicht über Claude

Auf dieser Website steht viel über Claude Code. Die Dokumentation entsteht trotzdem mit einem GPT-Modell, und der Grund ist unspektakulär: In meinem n8n liegt die OpenAI-API, Claude habe ich dort bisher nicht angebunden.

Dahinter steckt kein Qualitätsurteil, sondern Verwaltungsmüdigkeit. Jeder weitere Anbieter heißt neue Zugänge, neue Credentials, eine weitere Stelle, an der etwas abläuft. Das geht mir schon auf den Keks. Aktuell läuft deshalb alles in meinem n8n über GPT.

Genau deshalb überlege ich, OpenRouter auszuprobieren: ein Zugang, viele Modelle, und die Möglichkeit, andere überhaupt zu testen. Die Welt ist mittlerweile sehr vielfältig geworden, mein n8n ist es nicht.

Was offen ist

Drei Dinge, die ich nicht schönreden will.

Das Backup hat mich noch nie gerettet. Es ist reine Vorsorge, bisher ist nichts so gravierend schiefgegangen. Ein Backup, dessen Rückweg man nie gebraucht hat, ist ein Versprechen und kein Beweis.

Die Schwelle ist geraten. 25 Nodes klingt nach einer Kennzahl, ist aber ein Bauchgefühl. Ob 20 oder 35 besser wären, weiß ich nicht, weil ich es nicht gemessen habe.

Die Dokumentation ist unbewiesen. Ich lese sie nicht regelmäßig, also kann ich auch nicht sagen, wie oft das Modell einen Workflow falsch beschreibt. Der Nutzen zeigt sich erst, wenn die Suche mal danebengreift.

Was ich sagen kann: Seit dem 20. August läuft es ohne Eingriff, die nächtlichen Commits sind klein und sprechend, und der Bestand liegt an einem Ort, an dem ich Unterschiede sehe statt nur die letzte Fassung.