GitHub’s Agentic Workflows Automate Cross-Repository Documentation for Aspire Team

The Aspire team at GitHub has successfully implemented GitHub Agentic Workflows to automate the process of generating and reviewing documentation across separate code and documentation repositories. This development tackles a common challenge in software development: ensuring documentation keeps pace with rapid code changes. The automated system has enabled the team to merge 82 feature-documentation pull requests within a median of 44.8 hours after product pull requests for Aspire 13.3 and 13.4, with each draft reviewed by the feature engineer.

This approach addresses the traditional “documentation lag” where writers often had to reverse-engineer changes from closed pull requests, leading to delays in publishing accurate and up-to-date documentation. By integrating AI-powered automation, the team has streamlined the workflow without requiring additional headcount or process retraining.

Bridging the Repo Gap

A key challenge for the Aspire team was automating documentation for their product, which resides in `microsoft/aspire`, while its documentation lives in `microsoft/aspire.dev`. These are distinct repositories with different deployment targets and review chains. Cross-repository automation typically faces security hurdles, as broad repository-scoped tokens are not advisable. GitHub Agentic Workflows overcome this by providing a secure framework where an agent, powered by an AI model, can process work items with specific guardrails.

The agent receives read access and a prompt, while write operations are managed through a verifiable pipeline with explicit allow-lists. This setup ensures that the automation can operate effectively across repositories while adhering to stringent security policies.

How the Workflow Functions

The core of the system is a workflow named `pr-docs-check.md` within the `microsoft/aspire` repository. This workflow triggers when a pull request is closed against `main` or `release/*` branches and is marked as merged. It first uses a deterministic target branch resolver to identify where the documentation should land in the docs repository.

The agent then reads the code diff, scans linked issues, and determines if documentation updates are necessary. If required, it drafts content in a checked-out `microsoft/aspire.dev` workspace, adhering to established documentation standards and MDX conventions. The system then emits a `create_pull_request` safe-output, which triggers a companion job to post a marker comment on the original source pull request with a link to the newly created documentation pull request. This notifies the engineer who merged the code change, prompting them to review the AI-generated documentation draft.

Key Facts

Feature	Detail
Project	GitHub Aspire team
Tool	GitHub Agentic Workflows
Outcome	82 feature-docs PRs merged in median 44.8 hours post-product PR (Aspire 13.3/13.4)
Security	Agent with scoped GitHub App token, explicit allow-lists, human review

Impact on Documentation and Developers

This automation shifts the burden of initial documentation drafting from human writers to the AI agent. The engineers are now responsible for reviewing and approving the AI-generated drafts, ensuring accuracy. This allows human documentation writers to focus on more complex tasks such as creating narrative pages, sample programs, and conceptual walkthroughs that require human insight and creativity, rather than mechanical updates to reference pages. The system ensures that a feature is not considered “done” until its corresponding documentation is ready, effectively integrating documentation into the release cycle.

Source: GitHub Blog AI, https://github.blog/ai-and-ml/github-copilot/automating-cross-repo-documentation-with-github-agentic-workflows/