How AI-driven GitHub workflows cut documentation delays by 82%

Teams building developer tools know the frustration of chasing down documentation. When a feature ships, the engineer who built it is already focused on the next challenge, while writers scramble to reverse-engineer changes from code diffs. For the Aspire team—a small group of 10 engineers creating tools for distributed applications—the solution arrived in an unexpected place: GitHub Agentic Workflows.

By integrating AI-powered automation into their existing GitHub infrastructure, the team transformed a months-long bottleneck into a seamless process. The results speak for themselves: between releases 13.3 and 13.4, the median time from feature merge to merged documentation pull request dropped to just 44.8 hours. Crucially, every pull request was reviewed by the original engineer who shipped the feature—without adding a single new team member or overhauling internal processes.

From reverse-engineering to real-time documentation

The core challenge wasn’t writing documentation—it was coordinating across repositories. Aspire’s product code lives in microsoft/aspire, while its documentation site resides in microsoft/aspire.dev. Two distinct repositories, separate deployment pipelines, and completely independent review workflows. Most teams quickly automate same-repo documentation updates, but cross-repository workflows introduce serious friction.

Traditionally, the process followed a predictable (and painful) pattern:

• An engineer merges a feature pull request in microsoft/aspire.
• Weeks pass before a writer notices the change.
• The writer opens a new pull request, reviews the code diff, and contacts the engineer for clarification.
• The engineer, now deep into the next project, provides fragmented recollections.
• The documentation finally ships, sometimes against a release that has already moved forward.

This cycle isn’t just inefficient—it’s a tax on institutional knowledge. Features evolve faster than documentation can keep pace, leaving users to navigate undocumented changes alone.

How GitHub Agentic Workflows redefine automation

GitHub Agentic Workflows, developed by the GitHub Next team, introduces a fundamentally different approach to automation. Rather than treating GitHub Actions as a static script executor, it positions an AI model as the decision-making engine—bound by strict security constraints.

The workflow design is intentionally simple:

• A single markdown file (.github/workflows/pr-docs-check.md) contains both the workflow definition and an English-language prompt.
• Running gh workflow compile generates a traditional .lock.yml GitHub Actions workflow file.
• At runtime, the agent executes against the prompt using a restricted set of tools.

The critical innovation lies in the security model. Instead of granting the agent broad write permissions, it operates within a constrained sandbox:

• The agent analyzes code changes and linked issues to determine documentation needs.
• It drafts content directly in the documentation repository’s workspace.
• Rather than writing to GitHub directly, it emits structured intent (a JSON blob describing desired pull requests, issues, and comments).
• A separate, narrowly scoped safe-outputs handler materializes this intent through a per-workflow GitHub app with explicit allow-lists.

This separation ensures security reviewers can audit the automation without blocking innovation. The agent receives read access and a prompt; all writes route through a verified, minimal pipeline.

A seamless pipeline built on milestones and trust

The Aspire team’s automation hinges on a simple but powerful mapping: milestone titles in the product repository directly correspond to release branches in the documentation repository. When a pull request closes in microsoft/aspire, the workflow follows this deterministic resolution process:

• Extracts the milestone title from the pull request (for example, 13.4 maps to release/13.4 in aspire.dev).
• Parses linked issues for milestones using keywords like Fixes, Closes, or Resolves.
• Falls back to the main branch if no milestone is found.

This ensures the agent always knows exactly where to target the documentation update—no guesswork required.

Once the target branch is resolved, the agent performs three key tasks:

• Analyzes the code diff to identify what changed.
• Checks linked issues for additional context.
• Drafts documentation content in the microsoft/aspire.dev workspace, adhering to existing style guides, MDX conventions, and Starlight components.

The agent then emits a create_pull_request command as a safe output. The safe-outputs handler takes over:

• Creates a draft pull request titled [docs] Feature name with a docs-from-code label.
• Assigns the original reviewer from the source pull request as the reviewer—ensuring the engineer who approved the feature now reviews the documentation.
• Posts a comment on the original pull request with a link to the new documentation pull request.

This creates a feedback loop where the person who understands the feature best validates its documentation. No new processes, no retraining, just automation that respects existing workflows.

Shared foundations: when the tool and the docs speak the same language

The elegance of this solution extends beyond the automation itself. The tools used to build the documentation pipeline are built with the same frameworks as the documentation site. The Aspire documentation site uses Astro with Starlight, and so do the GitHub Agentic Workflows documentation pages.

This shared foundation isn’t just convenient—it reflects intentional design. The ecosystem includes:

• astro-mermaid for sequence diagrams
• starlight-llms-txt for language model integration
• starlight-sidebar-topics for structured navigation
• starlight-image-zoom for enhanced visuals
• @catppuccin/starlight for theming

This kinship between tooling and documentation creates a virtuous cycle: engineers who work with the automation understand the documentation system because they use the same components daily.

The future of documentation automation

The Aspire team’s experiment proves that AI-driven workflows can transform documentation from a bottleneck into a seamless extension of the development process. By leveraging GitHub’s existing infrastructure—without compromising security or adding overhead—they achieved an 82% reduction in documentation cycle time while maintaining high quality standards.

This approach isn’t limited to developer tools. Any team struggling with documentation lag, cross-repository coordination, or reverse-engineering overhead could benefit from this model. The key lies in balancing automation with human oversight, ensuring that AI handles the repetitive work while engineers retain control over what matters: the accuracy and clarity of their product’s story.

The next frontier may involve even tighter integration between code changes and documentation updates, perhaps with real-time previews or automated changelog generation. One thing is certain: the era of documentation as an afterthought is ending. With tools like GitHub Agentic Workflows, teams can finally keep pace with their own innovation.