Confluence-Dokumentation automatisch aus GitHub erzeugen

Die Lücke zwischen Code und Dokumentation

Die meisten Entwicklungsteams kennen eine Variante desselben Problems: Der Code entwickelt sich weiter, aber die Confluence-Seite aus der letzten Sprint-Planung bleibt unverändert. Dokumentationspflege konkurriert mit der Auslieferung neuer Funktionen, und die Dokumentation verliert — jedes Mal.

Die Ursache ist nicht Faulheit, sondern Reibung. Die Dokumentation liegt in einem anderen Werkzeug und Kontext und verlangt einen manuellen Wechsel genau dann, wenn Entwickler sich am stärksten auf den Code konzentrieren. Die Lösung sind nicht mehr Dokumentationserinnerungen im Ticket-Workflow, sondern Dokumentation, die sich selbst aktualisiert.

CodeDoc AI for Confluence verbindet dein GitHub-Repository über einen Webhook-Auslöser mit Confluence. Bei einem Push oder dem Zusammenführen eines Pull Requests liest die App das Repository, sendet die relevanten Dateien an deinen KI-Anbieter und veröffentlicht aktualisierte Dokumentation auf der Zielseite in Confluence — automatisch.

So funktioniert die Pipeline

Vor der Einrichtung hilft ein Überblick über den vollständigen Ablauf:

Die App basiert auf Atlassian Forge und läuft deshalb vollständig in Atlassians eigener Infrastruktur. Zwischen GitHub und Confluence sind keine externen Server beteiligt — nur dein ausgewählter KI-Anbieter erhält deinen Code, mit dem von dir bereitgestellten API-Schlüssel.

Schritt 1 — Ein GitHub Personal Access Token erstellen

CodeDoc AI benötigt Lesezugriff auf dein Repository. Empfohlen wird ein persönliches Zugriffstoken (Personal Access Token, PAT) mit dem Berechtigungsumfang repo (Lesezugriff genügt — die App schreibt nie in dein Repository).

Erstelle es unter GitHub → Settings → Developer settings → Personal access tokens. Wähle bei fein abgestuften Tokens „Repository contents: Read-only“. Aktiviere bei klassischen Tokens den repo Berechtigungsumfang. Die vollständige Token-Dokumentation von GitHub findest du unter docs.github.com.

Kopiere das Token sofort — GitHub zeigt es nicht erneut an.

Schritt 2 — GitHub in CodeDoc AI verbinden

Öffne CodeDoc AI aus dem Confluence-App-Menü und gehe zu Einstellungen → Git-Anbieter. Wähle GitHub, füge dein Zugriffstoken ein und klicke auf Verbinden und prüfen (Connect & Validate). Die App prüft das Token und bestätigt den Zugriff.

Git-Anbieter-Einstellungen — GitHub mit deinem persönlichen Zugriffstoken verbinden

Wenn du mehrere Git-Anbieter nutzt (zum Beispiel GitHub und GitLab), kannst du sie alle hier hinzufügen. Du kannst jeder Verbindung außerdem einen Anzeigenamen geben, um sie später bei der Repository-Auswahl leichter zu erkennen.

Schritt 3 — Dein Repository hinzufügen

Öffne den Tab Repositories . Klicke auf Repositories durchsuchen (Browse Repos) , um alle für das Token zugänglichen Repositories zu sehen. Grenze sie über das Suchfeld ein und klicke auf Auswahl hinzufügen (Add Selected). Alternativ klickst du auf URL hinzufügen (Add URL) und fügst die Repository-URL direkt ein — das funktioniert mit jedem Token-Typ und jeder Sichtbarkeitseinstellung.

Beim Hinzufügen per URL legst du außerdem den Branch fest, der dokumentiert werden soll (Standard: main). Hat dein Hauptbranch einen anderen Namen, ändere ihn hier.

GitHub-Repositories durchsuchen und hinzufügen — oder eine URL direkt einfügen, unabhängig von der Sichtbarkeit

Schritt 4 — Einen Dokumentationsauftrag erstellen

Ein Auftrag verbindet alles: Repository, Dokumentationsstil (Voreinstellung), Sprache und Ziel in Confluence. Öffne den Tab Aufträge (Jobs) und klicke auf Auftrag erstellen (Create Job).

Auftragserstellung — Repository, Voreinstellung, Sprache und Auslösertyp auswählen

Die wichtigsten Einstellungen für einen mit GitHub verbundenen Auftrag:

• Repository: Wähle das gerade hinzugefügte Repository.
• Voreinstellung: Wähle einen Dokumentationsstil. Entwicklerdokumentation (Developer Documentation) ist ein guter Ausgangspunkt — sie erzeugt neun strukturierte Abschnitte, darunter Architektur, API-Referenz und Fehlerbehebung. Siehe die vollständige Liste der Voreinstellungen für alle acht Optionen.
• Sprache: Die Sprache, in der die Seite geschrieben wird. Zehn Sprachen sind verfügbar, darunter Englisch, Deutsch, Französisch und Japanisch.
• Auslöser: Wähle Bei Commit (On Commit) (jeder Push) oder Bei Merge (On Merge) (nur zusammengeführte Pull Requests). Für die meisten Teams vermeidet „On Merge“ eine Dokumentationserzeugung bei jedem Push laufender Arbeit.
• Confluence-Bereich: Der Bereich, in dem die Seite erstellt oder aktualisiert wird.

Schritt 5 — Den GitHub-Webhook einrichten

Wenn du „On Commit“ oder „On Merge“ wählst, zeigt die Auftragserstellung eine Webhook-URL. Kopiere sie — im nächsten Schritt fügst du sie in GitHub ein.

Die Webhook-URL erscheint automatisch bei Auswahl eines automatischen Auslösers

Öffne in GitHub dein Repository → Settings → Webhooks → Add webhook:

1. 1
   Füge die Webhook-URL von CodeDoc AI in das Feld „Payload URL“ ein.
2. 2
   Setze Inhaltstyp (Content type) auf application/json.
3. 3
   Unter „Which events would you like to trigger this webhook?“ (Welche Ereignisse sollen auslösen?) wählst du Nur das Push-Ereignis (Just the push event) für „On Commit“ oder Einzelne Ereignisse wählen → Pull Requests (Let me select individual events → Pull requests) für „On Merge“.
4. 4
   Klicke auf Webhook hinzufügen (Add webhook). GitHub sendet ein Ping-Ereignis — die App nimmt es ohne weitere Meldung an.

Du benötigst nur eine Webhook-URL für alle Aufträge. Die App ordnet eingehende GitHub-Ereignisse anhand von Repository-URL und Branchname den richtigen Aufträgen zu. Die vollständige GitHub-Webhook-Dokumentation findest du unter docs.github.com.

Schritt 6 — Erzeugen und prüfen

Nachdem der Webhook registriert ist, pushe einen Commit auf den Branch (oder starte den Auftrag zum sofortigen Test manuell im Tab „Jobs“). Die App liest dein Repository, übergibt die ausgewählten Dateien an die KI und veröffentlicht das Ergebnis als Confluence-Seite.

Jede Erzeugung wird in der Ansicht Erzeugungsverlauf (Generation History) mit Tokenanzahl, Dateianzahl, verwendetem KI-Modell, Zeitstempel und direktem Link zur Confluence-Seite protokolliert.

Erzeugungsverlauf — jeder Durchlauf mit Tokennutzung, Dateianzahl und direktem Link zur Confluence-Seite

Optional: Vor der Veröffentlichung prüfen

Wenn du vor der Veröffentlichung eine Qualitätsprüfung möchtest — zum Beispiel in regulierten Umgebungen oder für Kundendokumentation — aktiviere Freigabe vor Veröffentlichung erforderlich (Require approval before publishing) in den Auftragseinstellungen. Die erzeugte Seite wird als Confluence-Entwurf mit dem Präfix [DRAFT] gespeichert. Du prüfst sie im Dashboard und veröffentlichst oder verwirfst sie manuell.

Bei häufig aktualisierter interner Entwicklerdokumentation erzeugt die Freigabe zusätzliche Reibung. Für Compliance-Dokumentation oder Einarbeitungsanleitungen für einen größeren Leserkreis ist sie eine sinnvolle Absicherung.

So sieht die Ausgabe aus

Hier siehst du ein Beispiel erzeugter Dokumentation in Confluence — automatisch aus einem Terraform-Infrastruktur-Repository mit der Voreinstellung „Developer Documentation“ erstellt. Die KI hat die eingesetzten Technologien erfasst, die Architektur beschrieben, die API-Oberfläche dokumentiert und Abhängigkeiten aufgelistet — alles als strukturierte Confluence-Seite formatiert.

Automatisch erzeugte Confluence-Seite — strukturierte Übersicht mit Technologien, Architektur und API-Referenz

Häufig gestellte Fragen