82 Doku-Pull-Requests, im Median 44,8 Stunden nach dem zugehörigen Produkt-PR gemerged, jeder reviewed von dem Ingenieur, der das Feature ausgeliefert hat: Das ist die Bilanz des Aspire-Teams für die Versionen 13.3 und 13.4. Zehn Entwickler, die Tools für verteilte Anwendungen bauen, hatten zuvor dasselbe Problem wie fast jedes Team – die Dokumentation lief dem Code hinterher. Ein Doku-Autor saß vor einem geschlossenen Pull Request und rekonstruierte, was sich geändert hatte, während dessen Autor längst weitergezogen war. Erschien die Doku endlich, war das Feature oft mehrfach veröffentlicht. Die Wende kam ohne neue Stellen und ohne Prozess-Umschulung, mit GitHub Agentic Workflows – und mit einer anderen Antwort auf die Frage, wer die Doku eigentlich schreibt.
Das Problem: Cross-Repo-Dokumentation ist der harte Teil
Das Produkt von Aspire lebt im Repository microsoft/aspire; die Doku-Website liegt in microsoft/aspire.dev – verschiedene Repos, verschiedene Deploy-Ziele, verschiedene Review-Ketten. Viele Teams automatisieren die Doku innerhalb eines Repos schnell. Aber wenn der Ort, an dem du die Doku schreibst, nicht der Ort ist, an dem der Code entsteht, wird es schwierig. Weitreichende Tokens für das gesamte Repo sind nicht mehr zeitgemäß. Eine verantwortungsvolle Sicherheitsstrategie – auch die des Aspire-Teams – schränkt sie ein. Das ist gut so, aber es wird zum Engpass, wenn die Doku woanders entstehen muss.
Der Standard-Workflow war jahrelang der gleiche: Ein Ingenieur bringt ein Feature in microsoft/aspire unter. Wochen später bemerkt ein Doku-Autor das Feature. Der Autor öffnet einen Pull Request, liest den Diff und kontaktiert den Ingenieur, um zu klären, was sich geändert hat. Der Ingenieur ist schon beim nächsten Feature, erinnert sich vage und antwortet mit einem halben Bild. Der Dokumentationsentwurf wird veröffentlicht – manchmal gegen eine Release, die längst draußen ist. Das nennt sich Reverse-Engineering-Steuer. Das Team brauchte eine Automatisierung, die Repos überbrückt, ohne einem Agenten einen Schreibzugriff auf alles zu geben. GitHub Agentic Workflows wurde zur Antwort.
Die Lösung: GitHub Agentic Workflows im Überblick
GitHub Agentic Workflows ist ein Projekt des GitHub-Next-Teams. Eine treffende Beschreibung: „GitHub Actions, aber mit einem Modell als Work-Item-Verarbeiter und Schutzleisten, die eine Sicherheitsprüfung bestehen.“ Das ist vereinfacht, aber zutreffend. Der Workflow wird als einzelne Markdown-Datei geschrieben – zum Beispiel .github/workflows/mein-workflow.md. Oben steht YAML-ähnliches Frontmatter, darunter eine englischsprachige Anweisung. Mit GitHub Agentic Workflows compile wird daraus eine normale GitHub-Action generiert, die als .lock.yml daneben liegt.
Zur Laufzeit arbeitet ein Agent gegen die Anweisung mit einem begrenzten Werkzeugsatz. Der Agent schreibt nicht direkt in GitHub. Er gibt eine Absicht aus – ein JSON-Blob, das beschreibt, welche Pull Requests, Issues oder Kommentare er erstellen möchte. Ein separater, eng begrenzter Job – der Safe-Outputs-Handler – setzt diese Absicht mit einer eigenen GitHub-App um. Der Agent bekommt nur Lesezugriff und eine Anweisung. Schreibvorgänge laufen über eine kleine, verifizierbare Pipeline mit expliziten Allowlisten. Die Sicherheitsabteilung nickt, und das Team kann loslegen.
Eine Randnotiz: Das Aspire-Team liebt es, wenn Werkzeuge, mit denen man baut, selbst mit den gleichen Werkzeugen gebaut wurden. Die Doku von GitHub Agentic Workflows basiert auf Astro und Starlight – genauso wie die Aspire-Doku. Starlight ist mit einem breiten Plugin-Ökosystem ausgestattet, das das Team nutzt. Das schafft eine echte Verbundenheit: Das Werkzeug zur Doku-Automatisierung und die Doku, die automatisiert wird, teilen sich dieselbe Grundlage. Das ist praktisch, weil das Mermaid-Sequenzdiagramm im nächsten Abschnitt in beiden Welten identisch gerendert wird.
Der Workflow im Detail: Vom Merge bis zur Doku
Der Workflow heißt pr-docs-check.md und lebt im Repository microsoft/aspire. Er startet bei einem geschlossenen Pull Request, und zwar nur wenn er tatsächlich gemerged wurde. Bevor der Agent aufwacht, führt ein deterministischer Bash-Abschnitt mehrere Schritte aus: Die Ziel-Branch auflösen, basierend auf dem Milestone des Pull Requests – zum Beispiel 13.4 wird zu release/13.4 im Doku-Repo. Falls kein Milestone gesetzt ist, wird der Milestone eines verknüpften Issues verwendet, geparst aus dem PR-Body. Wenn alles fehlschlägt, wird auf main gefallen. Diese Logik stellt sicher, dass die Doku am richtigen Ort landet, ohne dass der Agent raten muss.
Der Agent bekommt den Diff, scannt verknüpfte Issues und entscheidet, ob eine Doku nötig ist. Wenn ja, erstellt er den Inhalt direkt in einem ausgecheckten Arbeitsverzeichnis des Doku-Repos, folgt dabei den bestehenden Doc-Writer-Regeln – Stimme, MDX-Konventionen, Starlight-Komponenten. Am Ende gibt er einen Safe-Output create_pull_request aus. Der übernimmt dann: Der PR bekommt den Titel-Präfix [docs], ein Label, wird als Entwurf erstellt – niemals automatisch gemerged –, die Basis-Branch ist auf main oder release/ beschränkt, das Ziel-Repo ist microsoft/aspire.dev, und als Reviewer wird der Engineer eingesetzt, der das Feature im Ursprungs-PR freigegeben hat. Die Person, die das Feature kennt, prüft die Doku. Zusätzlich postet ein Begleit-Job einen Kommentar mit dem Doku-PR-Link im Quell-PR und räumt alte Kommentare auf.
Der Engineer, der gerade auf Merge geklickt hat, bekommt also innerhalb weniger Minuten die Nachricht: „Hier ist der Doku-Entwurf. Siehst du ihn dir an?“ Das ist die Umkehrung des bisherigen Prozesses: Früher musste der Doku-Autor den Engineer jagen, jetzt kommt die Doku zum Engineer.
Sicherheit durch klare Grenzen: Der Safe-Outputs-Ansatz
Die Sicherheitslösung beruht auf einem kleinen, trockenen Stück Frontmatter. Präzise formuliert: Der Agent erhält einen GitHub-App-Token, dessen Installation auf genau zwei Repositories beschränkt ist – das Produkt-Repo und das Doku-Repo. Kein anderes Repository in der Organisation ist erreichbar. Er kann Pull Requests nur gegen main oder release/ eröffnen. AGENTS.md und Abhängigkeitsmanifeste sind durch Policy blockiert. Falls das Erstellen des Pull Requests fehlschlägt – etwa wegen eines Netzwerkproblems oder Konflikts – wird automatisch stattdessen ein Issue erstellt, damit nichts verloren geht.
Das hat die Sicherheitsprüfung überzeugt. Das Denken des Agents ist unscharf, aber die Aktionsfläche ist klar definiert. Die Trennung zwischen Absicht und Ausführung ist ein eleganter Weg, um das Risiko von KI-Fehlern zu begrenzen. Der Agent kann vorschlagen, aber nicht handeln. Das Handeln ist durch Regeln festgezurrt, die der Mensch kontrolliert.
Die Zahlen: Was die Automatisierung brachte
Das Team hat die Ergebnisse über ein 30-Tage-Fenster gemessen, von Mai bis Juni 2026 – das entspricht dem Ende von Aspire 13.3 und dem Beginn von 13.4. In dieser Zeit wurden 396 Produkt-Pull-Requests im Aspire-Repo gemerged, verteilt auf verschiedene Branches. Der Workflow lief bei jedem einzelnen PR – insgesamt 396 Mal. Daraus entstanden 82 Doku-Pull-Requests im Doku-Repo, und alle wurden gemerged: 100 Prozent Erfolgsquote. Keiner wurde geschlossen, keiner blieb offen. Die Ziel-Branches verteilten sich auf release/13.3, release/13.4 und main. Die Zeit bis zum Merge betrug im Median 44,8 Stunden – bei einem Viertel unter 24 Stunden, bei 96 Prozent unter 7 Tagen.
Ein genauerer Blick zeigt: 396 Läufe zu 82 Pull Requests ist kein Fehler. Der Workflow läuft bei jedem Merge, aber viele Änderungen betreffen interne Refactorings, Testfixes oder Abhängigkeits-Updates ohne sichtbaren Effekt für Nutzer. Dass der Agent 300 Mal „keine Doku nötig“ sagt, ist ein Feature, kein Bug. Die 100-prozentige Merge-Rate zeigt, dass die Auswahl des Agents richtig ist. Die verschärfte Prompt-Version nach der ersten Fehlalarm-Phase zahlt sich aus.
Was funktionierte und was anfangs nicht klappte
Einige Entscheidungen erwiesen sich als Gold wert. Die Zuordnung von Milestone zu Release-Branch war die größte Hebelwirkung: Entwickler setzen Milestones ohnehin auf PRs und Issues, und so war die Ziel-Branch-Routing automatisch korrekt. Der Ansatz „Entwurf machen, SME als Reviewer“ war ebenfalls effektiv: Der Agent mergt nie, der Engineer bestätigt die Doku. Die eng begrenzte GitHub-App pro Workflow erlaubte eine Sicherheitsfreigabe und sorgte für einfaches Schlüssel-Management. Das Blockieren geschützter Dateien war ein Muss.
Aber es gab auch anfängliche Probleme. Der „Ist das Doku-würdig?“-Filter des Agents war zu großzügig: Er erstellte Entwürfe für rein interne Änderungen wie CI-Tweaks oder Logging-Refactorings – etwa 13 Prozent der ersten 69 PRs wurden deshalb geschlossen. Das Team verfeinerte die Definition von „benutzersichtbarer Änderung“ und fügte explizite Negativbeispiele hinzu. Ein weiteres Hindernis: Die Erstellung von Pull Requests über Repos hinweg verlangte ein gespiegeltes Checkout-Muster, das in der Doku nicht klar war. Das Team löste es, indem es das Doku-Repo zweimal auscheckte – einmal als aktuelles Arbeitsverzeichnis, einmal unter einem versteckten Ordner –, damit der Safe-Outputs-Handler das Ziel-Repo deterministisch findet. Große Diffs sprengten zudem das Prompt-Budget. Deshalb extrahiert ein Bash-Schritt vor dem Agenten die PR-Metadaten – verknüpfte Issues, Milestone, Basis-Branch – und gibt dem Agenten eine kompakte Struktur, statt einen riesigen Datenblock zu senden. Das ist das vorgesehene Muster des Frameworks und es funktioniert.
Das Ergebnis ist eine Veränderung im Denken des Teams. Ein Feature gilt nicht mehr als fertig, wenn die Doku fehlt. Die Doku hängt nicht mehr wie eine Blechdose am Auto hinterher. Der Engineer-Review ist das Tor, der Bot erledigt das Tippen. Das ersetzt keine Doku-Autoren, es entlastet sie: Sie können sich auf narrative Seiten, Beispiele und konzeptionelle Erläuterungen konzentrieren, während der Bot die mechanischen Aktualisierungen übernimmt, die niemandem Spaß machen.
Die Sicherheitsrichtlinien, die anfangs als Hindernis schienen, halfen dem Team, das System von Anfang an sicher zu designen. Starke Sicherheitsbedingungen machen Automatisierung vertrauenswürdiger. Wenn du ein Produkt in einem Repo entwickelst und die Doku in einem anderen pflegst – besonders innerhalb einer Sicherheitsgrenze –, schau dir GitHub Agentic Workflows an. Starte mit einem einzelnen Workflow wie pr-docs-check und miss, wie sich deine Zeit bis zur Doku verändert.
Quelle: github.blog
