GitHub Agentic Workflows: Wie KI Docs-Automatisierung revolutioniert

Die Frage "Wo sind die Dokumentationen?" ist für jedes Entwicklungsteam ein Albtraum. Oft müssen Tech Writer wochenlang auf Code-Änderungen warten, um sie zu dokumentieren – und bis dahin ist der Code bereits in Produktion. Das Microsoft Aspire-Team, das Tools für verteilte Anwendungen entwickelt, stand vor genau diesem Problem. Mit einer innovativen Lösung, basierend auf GitHub Agentic Workflows, gelang es ihnen, diesen manuellen Prozess vollständig zu automatisieren – und das ohne zusätzliche Stellen oder Prozessänderungen.

##

Seit der Einführung von GitHub Agentic Workflows in den Versionen Aspire 13.3 und 13.4 wurden 82 Dokumentations-Pull Requests innerhalb von durchschnittlich 44,8 Stunden nach dem Produkt-Release erstellt – jeder davon von den Entwicklern selbst überprüft. Die Lösung ermöglichte eine nahtlose Integration, ohne Sicherheitsrisiken oder manuelle Überarbeitungen.

##

Die größte Herausforderung: Automatisierung über Repository-Grenzen hinweg

Das Microsoft Aspire-Produkt (verfügbar unter microsoft/aspire) und die dazugehörige Dokumentation (microsoft/aspire.dev) liegen in separaten Repositories mit eigenen Deployment- und Review-Prozessen. Während viele Teams Automatisierungen innerhalb eines Repos leicht umsetzen können, wird es bei Cross-Repo-Prozessen komplex.

Die herkömmliche Vorgehensweise war mühsam:

• Entwickler:innen schließen ein Feature in microsoft/aspire.
• Tech Writer:innen bemerken die Änderungen erst Wochen später.
• Sie öffnen einen Pull Request, analysieren die Änderungen und kontaktieren die Entwickler:innen für Klärungen.
• Die Entwickler:innen sind bereits an neuen Features dran und haben nur vage Erinnerungen.
• Die Dokumentation wird veröffentlicht – manchmal für eine bereits veröffentlichte Version.

Dieser manuelle Prozess führte zu Verzögerungen, Inkonsistenzen und einem erheblichen Mehraufwand. Das Team suchte nach einer Lösung, die Cross-Repo-Automatisierung ohne weitreichende Berechtigungen ermöglicht – und wurde bei GitHub Agentic Workflows fündig.

##

GitHub Agentic Workflows: KI als Moderator für sichere Automatisierung

GitHub Agentic Workflows, ein Projekt des GitHub Next-Teams, lässt sich am besten als „GitHub Actions mit KI als Workflow-Manager und eingebauten Sicherheitsmechanismen“ beschreiben. Die Technologie kombiniert die vertraute Actions-Struktur mit einem KI-Agenten, der als intelligenter Vermittler zwischen Repositories agiert.

Die Funktionsweise im Überblick:

• Workflows werden als Markdown-Datei (z. B. .github/workflows/pr-docs-check.md) definiert. Die Datei enthält:
• Ein YAML-ähnliches Frontmatter für Metadaten.
• Eine klare Anweisung in natürlicher Sprache (englisch).

• Der Befehl gh workflows agent compile generiert eine `.lock.yml`, die als herkömmliche GitHub Actions-Workflow-Datei dient.

• Der KI-Agent führt die Anweisungen aus, hat jedoch keine direkten Schreibrechte auf GitHub. Stattdessen generiert er ein JSON-Intent-Dokument, das beschreibt, welche Pull Requests, Issues oder Kommentare erstellt werden sollen.

• Ein separater, sicherer Safe-Outputs-Handler (ein schmaler Job mit begrenzten Berechtigungen) setzt diese Intention um – ohne dass der Agent selbst auf GitHub zugreifen kann.

Diese Architektur erfüllt die strengen Sicherheitsanforderungen des Teams: Der Agent erhält nur Lesezugriff und eine klare Anweisung. Alle Schreiboperationen laufen über einen überprüfbaren, eingeschränkten Prozess mit expliziten Allow-Lists. Das Ergebnis? Die Sicherheitsabteilung ist zufrieden, und das Team spart wertvolle Zeit.

##

Ein harmonisches Ökosystem: Dokumentation und Automatisierung aus einem Guss

Ein oft unterschätzter Vorteil moderner Tools ist ihre Selbstkonsistenz. Die Dokumentation von GitHub Agentic Workflows selbst wird mit Astro und Starlight erstellt – genau wie die aspire.dev-Seite. Das Microsoft-Team nutzt dabei eine Reihe von Plugins, die das Schreiben und die Darstellung optimieren:

• astro-mermaid für Diagramme.
• starlight-llms-txt für KI-generierte Inhalte.
• starlight-image-zoom für hochauflösende Bilder.
• Das @catppuccin/starlight-Theme für ein ansprechendes Design.

Chris Swithinbank und das Starlight-Team haben eine Lösung geschaffen, die nicht nur funktional, sondern auch von Entwickler:innen für Entwickler:innen gestaltet wurde. Diese Konsistenz vereinfacht nicht nur die Wartung, sondern sorgt auch für eine nahtlose Integration der Automatisierung in die bestehende Dokumentationspipeline.

##

Die vollständige Pipeline: Von Code-Änderung zur automatisierten Dokumentation

Der Kern der Lösung ist ein Workflow namens `pr-docs-check.md`, der im microsoft/aspire-Repository läuft. Der Prozess beginnt, sobald ein Pull Request in den main- oder release/*-Branch gemerged wird.

Schritt 1: Ziel-Branch-Resolver (deterministisch und sicher)

Bevor der KI-Agent aktiv wird, klärt ein Bash-Skript den Ziel-Branch für die Dokumentation:

• Prüft den Milestone-Titel des Pull Requests (z. B. 13.4 → release/13.4 im aspire.dev-Repo).
• Analysiert verlinkte Issues (über Fixes/Closes/Resolves #N im PR-Body) und extrahiert deren Milestones.
• Nutzt den Base-Ref des Pull Requests, falls dieser einem Release-Branch entspricht.
• Fällt auf den main-Branch zurück, falls keine Milestones gefunden werden.

Diese Logik stellt sicher, dass die Dokumentation immer in den richtigen Branch der Dokumentation geschrieben wird – ohne manuelle Eingriffe oder Annahmen.

Schritt 2: KI-Agent generiert Dokumentations-Entwurf

Der Agent:

• Liest die Code-Änderungen im Pull Request.
• Analysiert verlinkte Issues für Kontext.
• Entscheidet, ob eine Dokumentation erforderlich ist.
• Erstellt einen Entwurf im `microsoft/aspire.dev`-Workspace, der den bestehenden Dokumentationsstandards entspricht (Starlight-Komponenten, MDX-Syntax, einheitlicher Stil).

Schritt 3: Safe-Outputs-Handler veröffentlicht Pull Request

Der Safe-Outputs-Handler übernimmt die endgültige Veröffentlichung:

• Titel: [docs] Automated documentation for [Feature-Name]
• Label: docs-from-code
• Status: draft (kein automatisches Mergen)
• Base Branch: Entweder main oder der Release-Branch (vom Agenten bestimmt)
• Ziel-Repo: microsoft/aspire.dev
• Reviewer: Die SME (Subject Matter Expert), die im ursprünglichen Pull Request die Feature-Änderung überprüft hat.

Zusätzlich postet der Workflow einen Kommentar im ursprünglichen Pull Request mit einem Link zum Dokumentations-PR und entfernt ältere Kommentare des gleichen Workflows bei erneuten Ausführungen.

##

Fazit: Eine Blaupause für zukünftige Automatisierungen

Die Integration von GitHub Agentic Workflows hat nicht nur die Dokumentationserstellung beschleunigt – sie hat auch eine neue Art der Zusammenarbeit zwischen Entwickler:innen und Tech Writer:innen ermöglicht. Durch die Automatisierung des manuellen Reverse-Engineerings können sich Teams auf das Wesentliche konzentrieren: die Entwicklung innovativer Features.

Mit dieser Lösung zeigt das Microsoft Aspire-Team, wie KI-gestützte Workflows nicht nur Effizienz steigern, sondern auch Sicherheit und Compliance gewährleisten können. Für andere Teams, die vor ähnlichen Herausforderungen stehen, könnte diese Pipeline ein Vorbild für die Zukunft der Software-Dokumentation sein – automatisiert, aber kontrolliert, intelligent, aber nachvollziehbar.