Von GitHub Wiki zu Confluence: Zwei Migrationswege im Vergleich

Warum Teams GitHub Wiki verlassen

GitHub Wikis sind einfach einzurichten und überraschend schwer zu skalieren. Die häufigsten Gründe für einen Wechsel:

• Eingeschränkte Suche — die Wiki-Suche deckt nur Titel und einen kleinen Teil des Seitentexts ab. Eine repositoryübergreifende Suche über mehrere Wikis fehlt.
• Grobe Berechtigungen — wer das Repository lesen kann, kann auch das Wiki lesen. Du kannst der Finanz- oder Rechtsabteilung keine einzelne Seite freigeben, ohne die Codebasis zugänglich zu machen.
• Außerhalb der Entwicklung schwer auffindbar — Menschen außerhalb der Entwicklung öffnen selten github.com/org/repo/wiki.
• Der Rest des Unternehmens sucht an einem anderen Ort — wenn jedes andere Team in Confluence schreibt, führen zwei Dokumentationsorte dazu, dass Leser keinen davon prüfen.

Zwei praktikable Wege

Im Wesentlichen gibt es zwei Wege für den Wechsel, die unterschiedliche Fragen beantworten:

Weg A — Wiki-Inhalte mit pandoc migrieren

Jedes GitHub Wiki ist selbst ein Git-Repository. Du kannst es klonen, Markdown mit dem folgenden Werkzeug in das Confluence-Speicherformat konvertieren: pandoc und das Ergebnis anschließend per REST an Confluence senden.

Schritt 1: Das Wiki-Repository klonen

git clone https://github.com/your-org/your-repo.wiki.git
cd your-repo.wiki
ls *.md

Schritt 2: Markdown in das Confluence-Speicherformat konvertieren

for f in *.md; do
  pandoc "$f" -f gfm -t html -o "out/${f%.md}.html"
done

Pandoc erzeugt XHTML, das für die meisten Seiten nahe genug am Confluence-Speicherformat liegt. Codeblöcke, Überschriften, Listen, Tabellen und Textformatierung werden sauber übernommen. Manuell prüfen musst du relative Seitenlinks, eingebettete Bilder und besondere GitHub-Makros (zum Beispiel <details> -Blöcke).

Schritt 3: Seiten über die Confluence-REST-API erstellen

POST /wiki/rest/api/content
{
  "type": "page",
  "title": "Architecture Overview",
  "space": { "key": "ENG" },
  "body": {
    "storage": {
      "value": "<html content from pandoc>",
      "representation": "storage"
    }
  }
}

Baue die Schleife in ein Skript ein, das jede Markdown-Datei einem Seitentitel und einer übergeordneten Seite zuordnet. Führe es zunächst in einem Testbereich aus, prüfe das Ergebnis und korrigiere das Skript, bevor du es auf den eigentlichen Bereich anwendest.

Weg B — Aus dem Quellcode mit CodeDoc AI neu erzeugen

Der zweite Weg überspringt die Migration vollständig. Statt das bestehende Wiki zu übertragen, verbindest du ein KI-Dokumentationswerkzeug mit dem Quellcode-Repository, wählst die Ausgabestruktur und lässt es frische Seiten direkt in Confluence schreiben.

CodeDoc AI for Confluence ist ein solches Werkzeug auf Basis von Atlassian Forge. Der Ablauf:

1. Einen KI-Anbieter verbinden — nutze deinen eigenen Schlüssel für Anthropic Claude, OpenAI oder Google Gemini.
2. GitHub verbinden mit einem persönlichen Zugriffstoken (Lesezugriff auf die zu dokumentierenden Repositories).
3. Das Repository hinzufügen — durchsuchen und auswählen oder die URL mit einem Branch einfügen.
4. Einen Auftrag erstellen — wähle eine Dokumentationsvoreinstellung (Developer Documentation für Entwicklerdokumentation, Onboarding Guide für Einarbeitung, Quick Reference als Kurzreferenz, Compliance & Audit usw.), eine Sprache und einen Auslöser.
5. Einen Zielbereich auswählen — wähle den Confluence-Bereich, in dem die Seite erstellt werden soll.
6. Ausführen — die KI liest den Code, erzeugt strukturierte Dokumentation und veröffentlicht sie als Confluence-Seite.

Was dieser Weg leistet — und was nicht

Das ist kein Migrator für Wiki-Inhalte. CodeDoc AI liest nicht deine GitHub-Wiki-Seiten, sondern den Quellcode im Hauptrepository. Die Ausgabe ist Dokumentation, die den heutigen Stand des Codes abbildet. Wenn dein Wiki ein Architekturentscheidungsprotokoll oder eine Einarbeitungsanleitung enthält, die nicht im Code steckt, musst du diese Inhalte separat übernehmen (dafür eignet sich Weg A).

Dafür bleibt die erzeugte Dokumentation ohne zusätzlichen Aufwand aktuell. Setze den Auslöser auf bei Commit per Webhook oder nach Zeitplan (täglich / wöchentlich / monatlich). Die Confluence-Seiten aktualisieren sich dann bei Codeänderungen automatisch. Das ursprüngliche Problem des Wikis — Seiten, die sich über Jahre vom Code entfernten — wird gelöst, indem die Abhängigkeit von manuellen Aktualisierungen vollständig entfällt.

Migriere keine ungenutzten Seiten

Der größte Fehler bei einer Wiki-Migration ist, sie als bloßen Kopiervorgang zu behandeln. Die meisten GitHub Wikis enthalten viele unvollständige Entwürfe, alte Architekturskizzen und nicht mehr gültige Anleitungen. Sie nach Confluence zu migrieren bewahrt die Altlasten — und nun sehen sie auch Stakeholder, die zuvor keinen Wiki-Zugriff hatten.

Vor beiden Wegen:

• Liste jede Wiki-Seite — ls *.md im Wiki-Repository auf und übertrage die Liste in eine Tabelle.
• Kennzeichne jede Seite mit behalten, neu erzeugen oder archivieren.
• Behalte die tatsächlich unersetzbaren Seiten — Entscheidungsprotokolle, Nachanalysen und Betriebsanleitungen, die auf menschlichem Wissen statt auf Code beruhen.
• Erzeuge die Seiten zu „Was macht dieser Code?“ aus dem Quellcode neu.
• Archiviere den Rest. Wenn eine Seite seit zwölf Monaten niemand angefasst hat, ist sie mit hoher Wahrscheinlichkeit keine tragende Grundlage.

Ein kombinierter Ablauf

Für die meisten Teams ist diese Reihenfolge am sinnvollsten:

1. Prüfe das Wiki. Kennzeichne Seiten mit behalten / neu erzeugen / archivieren.
2. Migriere die mit behalten markierten Seiten mit pandoc + REST-API in einen neuen Confluence-Bereich.
3. Installiere CodeDoc AI, wähle denselben Confluence-Bereich und richte Aufträge für jedes Repository ein.
4. Verbinde die Aufträge mit deiner CI: Webhook-Auslösung bei einem Push auf main, damit die Dokumentation mit dem Code aktualisiert wird.
5. Archiviere das alte GitHub Wiki — halte es als schreibgeschützte Referenz vor und verweise in der README auf Confluence.

Häufig gestellte Fragen