Seminar Kroki – Automatisierung mit CLI, Skripten und CI/CD

Diagrammerzeugung in wiederholbare Build-Prozesse überführen

Ein Diagramm ist erst dann zuverlässig, wenn seine Erzeugung nicht von einem einzelnen Arbeitsplatz oder einer manuellen Klickfolge abhängt. Das Seminar zeigt, wie Kroki-Quellen mit CLI, Skripten und CI/CD-Pipelines automatisch entdeckt, konvertiert, geprüft und als Artefakte bereitgestellt werden.

Die zweitägige Dauer schafft ausreichend Raum für Kommandozeilenarbeit, Fehlerbehandlung und den Aufbau einer vollständigen Pipeline. Neben dem Erfolgsfall werden unveränderte Quellen, Zeitüberschreitungen, nicht unterstützte Typen, fehlerhafte Syntax und kontrollierte Wiederholungen behandelt.

Inhaltsübersicht

• Kroki CLI, Konfigurationsdateien und Endpunkte
• Einzel- und Batch-Konvertierung
• Kodieren, Dekodieren und Arbeiten mit Standardeingabe
• Skriptstruktur für mehrere Diagrammtypen
• Quellenerkennung, Dateinamen und Ausgabeordner
• Hash-Caching und inkrementelle Builds
• Validierung, Rückgabecodes und Protokolle
• CI/CD-Jobs, Artefakte und Regressionstests

Zielgruppe

Das Seminar richtet sich an Entwickler, Build- und Release-Verantwortliche, DevOps-Fachkräfte, technische Redakteure und Plattformteams. Es eignet sich besonders für Repositories mit vielen Diagrammquellen oder für Organisationen, die Rendering und Dokumentationsaufbau vereinheitlichen möchten.

Voraussetzungen

Erforderlich sind sichere Grundkenntnisse der Kommandozeile, Versionsverwaltung und einfacher Skriptlogik. Erfahrung mit einer CI/CD-Plattform ist hilfreich, aber nicht zwingend. Ein erreichbarer Kroki-Endpunkt oder eine lokale Testinstanz wird vorausgesetzt.

Lernstrecke Schritt für Schritt

1. Schritt 1: CLI-Funktionen und Konfiguration prüfen. Konvertieren, Kodieren, Dekodieren, Hilfetexte und Versionsabfrage werden systematisch getestet. Endpunkt und Zeitüberschreitung werden in einer nachvollziehbaren Konfiguration hinterlegt.
2. Schritt 2: Einzeldateien kontrolliert konvertieren. Diagrammtyp und Ausgabeformat werden zunächst automatisch aus Dateiendung und Zielnamen abgeleitet. Anschließend werden explizite Angaben und Standardeingabe verwendet.
3. Schritt 3: Ein Batch-Verzeichnis verarbeiten. Quellen werden rekursiv gefunden, nach Endung klassifiziert und in eine parallele Ausgabestruktur geschrieben. Nicht unterstützte Dateien werden protokolliert statt stillschweigend ignoriert.
4. Schritt 4: Dateinamen und Zielpfade standardisieren. Regeln für Kollisionen, Groß- und Kleinschreibung, Sprachvarianten und mehrere Ausgabeformate werden definiert. Der Build bleibt auf unterschiedlichen Betriebssystemen reproduzierbar.
5. Schritt 5: Eine Skriptbibliothek aufbauen. Aufruf, Zeitüberschreitung, Wiederholung, Fehlerausgabe und Dateischreiben werden in wiederverwendbare Funktionen getrennt. Konfiguration und Geheimnisse bleiben außerhalb des Quellcodes.
6. Schritt 6: Kodierung und Dekodierung automatisieren. GET-Adressen werden aus Quellen erzeugt und bei Bedarf wieder in Text zurückgeführt. Die Funktion dient unter anderem zur Analyse kodierter Protokolleinträge.
7. Schritt 7: Inkrementelle Builds mit Hashes umsetzen. Ein Quellhash entscheidet, ob ein Diagramm neu gerendert werden muss. Diagrammtyp, Optionen und Endpunktversion werden in den Cache-Schlüssel einbezogen.
8. Schritt 8: Qualitätsprüfungen vor dem Rendering ausführen. Leere Quellen, zu große Dateien, unerlaubte Endungen und fehlende Metadaten werden früh erkannt. Die Pipeline meldet klare Ursachen und bricht nach festgelegten Regeln ab.
9. Schritt 9: Einen CI/CD-Job erstellen. Der Job richtet Werkzeuge ein, startet oder adressiert Kroki, rendert Quellen und sammelt Ausgaben. Cache, Artefaktlaufzeit und parallele Verarbeitung werden passend konfiguriert.
10. Schritt 10: Fehler und Wiederholungen beherrschen. Netzwerkfehler, Zeitüberschreitungen und temporäre Dienststörungen werden von Syntaxfehlern getrennt. Nur geeignete Fehlerklassen führen zu begrenzten Wiederholungen.
11. Schritt 11: Regressionen sichtbar machen. Ausgabedateien, Metadaten oder gerasterte Vorschaubilder werden verglichen. Zulässige Layoutänderungen werden von unbeabsichtigten Abweichungen unterschieden.
12. Schritt 12: Veröffentlichung und Nachvollziehbarkeit sichern. Artefakte erhalten Build- und Quellbezug. Eine Freigaberegel verhindert, dass veraltete oder fehlerhaft erzeugte Diagramme in Dokumentationen übernommen werden.

Praxisaufgaben

• Ein Verzeichnis mit gemischten Diagrammquellen automatisch konvertieren.
• Ein Hash-basiertes inkrementelles Rendering mit sauberem Cache-Schlüssel umsetzen.
• Fehlerklassen definieren und geeignete Wiederholungsregeln implementieren.
• Einen CI/CD-Job mit Cache, Artefakten und verständlicher Protokollierung erstellen.
• Eine kontrollierte Diagrammänderung als Regression erkennen und freigeben.

Kompetenzziele

• Kroki CLI sicher konfigurieren und für Einzel- sowie Batch-Aufgaben verwenden.
• Robuste Rendering-Skripte mit klarer Fehlerbehandlung entwickeln.
• Inkrementelle Builds und wiederverwendbare Ausgabestrukturen gestalten.
• Diagrammrendering in CI/CD-Pipelines integrieren und nachvollziehbar veröffentlichen.
• Technische Fehler von inhaltlichen Diagrammfehlern unterscheiden und gezielt behandeln.