Seminar MkDocs – CI/CD, Build und Deployment

Eine professionelle Dokumentationsplattform wird nicht manuell aus einem Entwicklerverzeichnis veröffentlicht. Quellprüfung, reproduzierbarer Build, Qualitäts-Gates, Artefaktübergabe, Deployment und Rollback bilden eine kontrollierte Lieferkette.

Inhaltsübersicht

• Zielsetzung
• Zielgruppe
• Voraussetzungen
• Seminarinhalte
• Praxisübungen
• Methodik

Zielsetzung

Eine vollständige, plattformneutral beschriebene Pipeline wird entwickelt und an einem Beispielprojekt umgesetzt. Dabei werden lokale und zentrale Prüfungen, Umgebungsparameter, Artefakte und Freigabestufen klar getrennt.

Zielgruppe

DevOps-Teams, Build- und Release-Verantwortliche, Administratoren, technische Projektleiter und Entwickler mit Verantwortung für Dokumentationsplattformen.

Voraussetzungen

Sicherer Umgang mit Git, Kommandozeile und YAML; Grundkenntnisse in MkDocs und einem CI-System.

Seminarinhalte

Die Themen werden in einer festen Arbeitsfolge aus Analyse, Einrichtung, Umsetzung und Prüfung bearbeitet.

CI/CD-Stufenmodell

1. Schritt 1: Ereignisse für Prüfung, Vorschau, Freigabe und Veröffentlichung festlegen.
2. Schritt 2: Pipeline-Stufen nach Geschwindigkeit, Risiko und Abhängigkeit ordnen.
3. Schritt 3: Artefakte, Protokolle und Freigaben als überprüfbare Ergebnisse definieren.
4. Schritt 4: Abbruch-, Wiederanlauf- und Fehlerregeln vor der Implementierung festlegen.

Reproduzierbare Pipeline-Umgebung

1. Schritt 1: Python-Version und Abhängigkeiten eindeutig festschreiben.
2. Schritt 2: Builds in isolierten, kurzlebigen Umgebungen mit identischen Befehlen ausführen.
3. Schritt 3: Konfigurationsvarianten, Umgebungswerte und Secrets voneinander trennen.
4. Schritt 4: Caches nur mit belastbaren Schlüsseln und sicherem Fallback verwenden.

Qualitätsgates im Build

1. Schritt 1: Konfiguration, Markdown und Metadaten mit schnellen Prüfungen validieren.
2. Schritt 2: Strikten MkDocs-Build als verbindliches Gate einrichten.
3. Schritt 3: Links, Anker, Medienpfade und erzeugte HTML-Struktur kontrollieren.
4. Schritt 4: Fehlerausgaben mit Datei, Zeile, Regel und Verantwortungsbereich erzeugen.

Build-Artefakte und Vorschauumgebungen

1. Schritt 1: Statische Ausgabe als unveränderliches, versioniertes Artefakt behandeln.
2. Schritt 2: Quellrevision, Build-Zeitpunkt und Abhängigkeitsstand nachweisbar einbetten.
3. Schritt 3: Isolierte Vorschauen für Reviews mit eindeutiger Lebensdauer bereitstellen.
4. Schritt 4: Artefakte zwischen Pipeline-Stufen weitergeben statt erneut zu bauen.

Deployment und Veröffentlichung

1. Schritt 1: Zielsystem und Übertragungsstrategie nach Betriebsanforderung auswählen.
2. Schritt 2: Veröffentlichung atomar oder über versionierte Zielverzeichnisse durchführen.
3. Schritt 3: Berechtigungen, Cache-Invalidierung und konsistente Assets berücksichtigen.
4. Schritt 4: Produktiven Stand nach Veröffentlichung technisch und fachlich prüfen.

Rollback und Wiederanlauf

1. Schritt 1: Vorherige Artefakte und eindeutige Rückfallpunkte bereithalten.
2. Schritt 2: Fehlgeschlagene Deployments ohne Mischzustand abbrechen.
3. Schritt 3: Rollback-Auslöser, Verantwortlichkeit und Prüfschritte dokumentieren.
4. Schritt 4: Wiederanlauf und nachgelagerte Ursachenanalyse praktisch testen.

Qualitätsmodell und Prüfstrategie

1. Schritt 1: Inhaltliche, strukturelle, technische, visuelle und betriebliche Fehler unterscheiden.
2. Schritt 2: Fehler nach Auswirkung, Erkennbarkeit und Korrekturaufwand priorisieren.
3. Schritt 3: Lokale Prüfung, Review-Gate und vollständige Pipeline-Prüfung trennen.
4. Schritt 4: Akzeptanzkriterien und zeitlich begrenzte Ausnahmen dokumentieren.

Lieferkette, Abhängigkeiten und Plugins

1. Schritt 1: Direkte und transitive Python-Abhängigkeiten vollständig inventarisieren.
2. Schritt 2: Versionen, Herkunft und unterstützte Bereiche festschreiben.
3. Schritt 3: Plugins als ausführbaren Code mit Berechtigungen und Seiteneffekten bewerten.
4. Schritt 4: Aktualisierungs- und Sicherheitsprüfung in den Lebenszyklus integrieren.

Praxisübungen

• Eine Pipeline mit getrennten Prüf-, Build- und Veröffentlichungsstufen entwerfen
• Ein versioniertes Artefakt erzeugen und kontrolliert in eine Zielumgebung übergeben
• Fehlerfall, Freigabe und Rollback anhand eines Runbooks simulieren

Methodik

Fachliche Einführung, nachvollziehbare Demonstration, angeleitete Umsetzung, selbstständige Übungsphasen, strukturierte Fehleranalyse und gemeinsame Qualitätskontrolle wechseln einander ab. Alle Arbeitsschritte werden an einem zusammenhängenden Beispielprojekt durchgeführt.