- Published on
Automating cross-repo documentation with GitHub Agentic Workflows
- Authors
- Name
- DeepHorus
The Aspire team at Microsoft has successfully automated cross-repository documentation generation using GitHub Agentic Workflows, dramatically reducing the time between product changes and documentation publishing. For releases 13.3 and 13.4, the team merged 82 feature-documentation pull requests at a median of 44.8 hours after the corresponding product pull request, with every doc reviewed by the engineer who shipped the feature. This achievement closed the gap that previously left documentation lagging behind, a common pain point across development teams.
The challenge stemmed from the team's architecture: product code resides in the microsoft/aspire repository, while the documentation site lives in a separate repo, microsoft/aspire.dev. Different repositories, deploy targets, and review chains made cross-repo automation difficult due to security constraints on repo-scoped tokens. Historically, the process relied on a manual, reverse-engineering tax—documentation writers would discover changes weeks later, resulting in delayed and incomplete docs.
GitHub Agentic Workflows, a project from the GitHub Next team, provided the solution. It functions like GitHub Actions but uses a large language model as the work-item processor, with built-in guardrails that satisfy security reviews. Workflows are authored as markdown files with YAML frontmatter and an English prompt, then compiled into a lock.yml file that runs as a standard GitHub Actions workflow.
A critical design feature is that the agent does not write directly to GitHub. Instead, it emits a JSON blob describing the pull requests, issues, or comments it wants to create. A separate, narrowly scoped job—the safe-outputs handler—materializes that intent using a per-workflow GitHub app. This separation ensures the agent has read-only access, with writes going through a verifiable pipeline with explicit allow-lists, passing security reviews.
The Aspire team built prototypes within microsoft/aspire, resulting in significant efficiency gains. The 44.8-hour median turnaround time for docs represents a dramatic improvement over previous delays. This was achieved without new headcount or process retraining, simply by rethinking how documentation responsibilities are automated.
The team also noted the synergy between their stack and that of GitHub Agentic Workflows. Both the aspire.dev site and the workflow's documentation are built with Astro and Starlight, leveraging a rich ecosystem of plugins. This alignment underscores the project's developer-friendly approach.
Looking ahead, cross-repo automation with agentic workflows could become a standard pattern for teams grappling with the documentation lag. By enabling safe, autonomous generation of pull requests across repositories, it addresses a fundamental bottleneck in software delivery. The Aspire team's success demonstrates that with the right security architecture, AI-driven documentation can keep pace with rapid feature development, potentially reshaping how teams approach documentation in distributed repo environments.
