Automating Cross-Repo Documentation with GitHub Agentic Workflows
Eliminating documentation delays with AI-powered workflows.
1Solving Documentation Gridlock
The Aspire team leveraged GitHub's new Agentic Workflows to break the cycle of late documentation. This AI-assisted system securely bridges code and documentation repositories.
2Cross-Repo Challenge
With code in microsoft/aspire and docs in microsoft/aspire.dev, traditional automation hit security walls. Broad tokens were risky, while repo-specific restrictions created bottlenecks.
3Agentic Workflows Architecture
The markdown-based system processes AI-generated JSON intents through a narrowly-scoped GitHub App. Write permissions are strictly confined to a secure pipeline.
4Version Mapping Mechanism
A bash script linking product milestones to doc release branches eliminates target branch ambiguity. Version alignment is guaranteed before the agent activates.
5Intelligent Doc Generation
The agent scans code changes and linked issues to determine documentation needs. It produces content following existing MDX templates and opens draft PRs.
6Security Layers
The safe-outputs handler enforces strict controls from PR title prefixes to labels. Auto-merge remains disabled, requiring human approval for all changes.
7SME-Centric Review
Engineers who approved features are automatically assigned as doc PR reviewers, ensuring subject matter expertise flows into documentation.
8Feedback Loop
Source PR comments and minimized old threads maintain communication in one channel. Engineers see documentation drafts immediately after merging.
9Performance Metrics
For Aspire 13.3 and 13.4, 82 doc PRs merged at median 44.8 hours. No feature shipped undocumented, with zero additional staffing or training costs.
10Technical Stack Alignment
Both Agentic Workflows docs and aspire.dev site use Astro+Starlight. Shared infrastructure enables seamless component reuse like Mermaid diagrams.
11Advancing DevOps Culture
This solution makes documentation a natural CI/CD pipeline component. It raises quality standards without increasing engineer workload.