GitLab Pages fuer Projektdokumentation: Automatisch veroeffentlichen bei jedem Merge

1. Warum Dokumentation so oft veraltet

Projektdokumentation veraltet fast immer aus demselben Grund: Sie liegt getrennt vom Code, muss manuell aktualisiert und manuell veroeffentlicht werden, und dieser zweite Schritt wird im Alltag zuverlaessig vergessen. Ein Entwickler aendert die API, aktualisiert vielleicht noch die lokale Markdown-Datei, vergisst aber den Export und Upload auf den internen Webserver. Sechs Monate spaeter verlassen sich neue Teammitglieder auf eine Dokumentation, die mit dem tatsaechlichen Code nichts mehr zu tun hat.

GitLab Pages loest genau dieses Problem, indem die Veroeffentlichung der Dokumentation zu einem regulaeren CI/CD-Job wird, der bei jedem Merge in den Hauptbranch automatisch laeuft. Die Dokumentation wird damit zu einem Artefakt der Pipeline wie jedes andere auch, mit derselben Zuverlaessigkeit wie ein Build oder ein Test, und die Frage "ist die Doku aktuell?" reduziert sich auf "ist die letzte Pipeline gruen?".

2. Das Grundprinzip: der pages-Job und das public-Verzeichnis

GitLab Pages funktioniert nach einer einfachen Konvention: Ein Job mit dem reservierten Namen pages muss als Artefakt ein Verzeichnis namens public/ erzeugen. Alles, was in diesem Verzeichnis liegt, wird nach erfolgreichem Pipeline-Lauf automatisch unter einer von GitLab verwalteten URL bereitgestellt, typischerweise https://gruppe.gitlab.io/projekt bei GitLab.com oder einer entsprechenden Subdomain auf einer selbst gehosteten Instanz. Es ist kein separater Deploy-Schritt und kein externer Webserver noetig.

Dieser Mechanismus ist bewusst werkzeugunabhaengig: Es spielt keine Rolle, ob das public/-Verzeichnis von MkDocs, Sphinx, Hugo, einem PHPDoc-Generator oder einem simplen Shell-Skript erzeugt wird. Fuer GitLab zaehlt ausschliesslich das Endergebnis im vorgegebenen Verzeichnis, was den Einstieg unabhaengig vom gewaehlten Dokumentations-Werkzeug sehr niedrigschwellig macht.

3. MkDocs-Dokumentation automatisch bauen und veroeffentlichen

Fuer textbasierte Dokumentation in Markdown ist MkDocs eine bewaehrte Wahl, weil es aus einer einfachen Verzeichnisstruktur eine durchsuchbare, navigierbare Website erzeugt. Die Pipeline-Konfiguration dafuer ist ueberschaubar: Ein Job installiert MkDocs (idealerweise ueber ein vorgefertigtes Docker-Image, um Installationszeit zu sparen), fuehrt mkdocs build aus und deklariert das erzeugte Verzeichnis als Artefakt fuer den pages-Job.

Wichtig ist, den Job auf den relevanten Branch zu beschraenken, meist main oder master, damit nicht jeder Feature-Branch die produktive Dokumentation ueberschreibt. Ebenso empfiehlt sich ein rules-Block statt des aelteren only/except, um die Bedingung klar und wartbar zu formulieren.

# .gitlab-ci.yml
stages:
  - build
  - deploy

pages:
  stage: deploy
  image: python:3.12-slim
  script:
    - pip install --quiet mkdocs mkdocs-material
    - mkdocs build --site-dir public
  artifacts:
    paths:
      - public
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'

4. PHPDoc-generierte API-Referenz automatisch veroeffentlichen

Fuer ein PHP-Projekt wie ein Magento-Modul ist die API-Referenz aus PHPDoc-Kommentaren mindestens genauso wertvoll wie eine handgeschriebene Anleitung, insbesondere fuer interne Bibliotheken mit vielen wiederverwendeten Interfaces. Werkzeuge wie phpDocumentor lesen die im Projekt vorhandenen PHPDoc-Bloecke (die gemaess Projektstandard ohnehin fuer jede Klasse und Methode gepflegt werden) aus und generieren daraus eine vollstaendig verlinkte HTML-Referenz, ohne dass Entwickler zusaetzlichen Dokumentationsaufwand betreiben muessen.

In der Pipeline laesst sich dieser Schritt gut mit dem eigentlichen Composer-Build kombinieren: Nach composer install wird phpdoc run mit dem Zielverzeichnis public/ ausgefuehrt. Bei groesseren Codebasen lohnt sich ein Cache fuer die phpDocumentor-Zwischenergebnisse, um die Build-Zeit bei wiederholten Pipeline-Laeufen spuerbar zu senken.

# .gitlab-ci.yml
pages:
  stage: deploy
  image: phpdoc/phpdoc:3
  script:
    - phpdoc run -d app/code/Mironsoft -t public --title "Mironsoft API-Referenz"
  artifacts:
    paths:
      - public
  cache:
    key: phpdoc-cache
    paths:
      - .phpdoc/cache
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      changes:
        - app/code/**/*.php

5. Vorschau-Deployments fuer Dokumentations-Aenderungen in Merge Requests

Ein besonders nuetzliches Feature sind Merge Request Pages: Statt Dokumentationsaenderungen erst nach dem Merge sichtbar zu machen, kann ein Job so konfiguriert werden, dass er fuer jeden offenen Merge Request eine eigene Vorschau-URL erzeugt. Reviewer sehen dann direkt im gerenderten Layout, ob eine Aenderung an der Dokumentation korrekt aussieht, statt den Markdown-Quelltext im Diff mental rendern zu muessen.

Technisch wird dafuer ein zusaetzlicher Job mit dem Pfad-Praefix pages: und der passenden rules-Bedingung fuer Merge-Request-Pipelines definiert. GitLab zeigt den Link zur Vorschau dann direkt in der Merge-Request-Uebersicht an, was den Review-Prozess fuer Dokumentationsaenderungen erheblich beschleunigt und Formatfehler bereits vor dem Merge sichtbar macht.

# Zusaetzlicher Job fuer Merge-Request-Vorschauen
pages:mr-preview:
  stage: deploy
  image: python:3.12-slim
  script:
    - pip install --quiet mkdocs mkdocs-material
    - mkdocs build --site-dir public
  artifacts:
    paths:
      - public
  environment:
    name: review/mr-$CI_MERGE_REQUEST_IID
    url: "$CI_PAGES_URL"
    auto_stop_in: 1 week
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

6. Zugriffsschutz fuer interne Dokumentation

Nicht jede Dokumentation soll oeffentlich zugaenglich sein, insbesondere interne API-Referenzen oder Architekturentscheidungen mit sensiblen Details. GitLab Pages bietet dafuer Access Control, das die Sichtbarkeit an die Projekt- oder Gruppenmitgliedschaft koppelt: Nur Personen mit mindestens Guest-Zugriff auf das Repository koennen die veroeffentlichte Seite ueberhaupt aufrufen, alle anderen erhalten eine Weiterleitung zum GitLab-Login.

Diese Einstellung findet sich unter Settings > General > Visibility, project features, permissions > Pages und sollte fuer interne Dokumentation standardmaessig aktiviert werden, waehrend oeffentliche Open-Source-Dokumentation bewusst ohne diese Einschraenkung veroeffentlicht wird. Wichtig zu wissen: Access Control auf GitLab.com erfordert, dass sowohl die Pages-Website als auch der Betrachter bestimmte Voraussetzungen erfuellen, weshalb bei selbst gehosteten Instanzen die genaue Konfiguration in der gitlab.rb zusaetzlich geprueft werden sollte.

7. Mehrsprachige und versionierte Dokumentation abbilden

Bei laenger laufenden Projekten stellt sich frueher oder spaeter die Frage, ob die Dokumentation zu mehreren Major-Versionen parallel verfuegbar sein soll. Eine bewaehrte Loesung ist, die Pipeline so zu erweitern, dass sie nicht nur den aktuellen Stand nach public/ baut, sondern zusaetzlich versionsspezifische Unterverzeichnisse wie public/v1/ und public/v2/ erzeugt, gesteuert ueber Git-Tags oder einen dedizierten Dokumentations-Branch pro Major-Version.

Fuer mehrsprachige Inhalte funktioniert dasselbe Prinzip mit Sprach-Unterverzeichnissen wie public/de/ und public/en/, wobei MkDocs mit dem Plugin mkdocs-static-i18n diese Struktur direkt unterstuetzt. In beiden Faellen bleibt der Grundmechanismus identisch: Der pages-Job liefert am Ende ein vollstaendiges public/-Verzeichnis, unabhaengig davon, wie komplex die interne Struktur darunter ist.

8. Redirects und benutzerdefinierte Fehlerseiten einrichten

Wird eine Dokumentationsstruktur umbenannt oder ein Kapitel verschoben, fuehren alte, extern verlinkte URLs sonst ins Leere. GitLab Pages unterstuetzt eine _redirects-Datei nach dem von statischen Hosting-Diensten bekannten Format, die im public/-Verzeichnis abgelegt wird und einfache Pfad-Weiterleitungen ohne serverseitige Logik ermoeglicht. Fuer MkDocs-Projekte laesst sich diese Datei automatisiert aus einer Liste bekannter Umbenennungen generieren, statt sie manuell zu pflegen.

Ebenso wichtig ist eine sinnvolle 404.html im Wurzelverzeichnis von public/, die GitLab Pages automatisch fuer nicht existierende Pfade ausliefert. Eine Fehlerseite mit Verweis auf die Startseite und die Suchfunktion reduziert die Absprungrate erheblich, verglichen mit der generischen GitLab-Standardfehlerseite, die keinerlei Kontext zur eigentlichen Dokumentation liefert.

9. Typische Stolperfallen und wie man sie behebt

Der haeufigste Fehler ist ein falsch benannter Job: Nur ein Job, der exakt pages heisst (bei neueren GitLab-Versionen auch mit dem Praefix pages: fuer mehrere parallele Pages-Jobs), wird von GitLab als Pages-Deployment erkannt. Ein Job namens build-docs, der zwar ein public/-Verzeichnis erzeugt, aber nicht so heisst, veroeffentlicht nichts, auch wenn die Pipeline erfolgreich durchlaeuft.

Ein zweiter haeufiger Stolperstein ist ein falscher Pfad in site-dir oder ein relativer Pfad, der nicht mit dem artifacts.paths-Eintrag uebereinstimmt, wodurch das Artefakt zwar erzeugt, aber leer oder unvollstaendig hochgeladen wird. Die folgende Tabelle fasst die wichtigsten Konfigurationspunkte und ihre haeufigsten Fehlerquellen zusammen.

10. Zusammenfassung

11. FAQ: GitLab Pages fuer Dokumentation: Das Wichtigste auf einen Blick