Automating cross-repo documentation with GitHub Agentic Workflows

For years, the Aspire team's documentation process followed a familiar, miserable pattern: an engineer ships a feature, moves on, and weeks later a writer is squinting at a closed pull request trying to reverse-engineer what actually changed. By the time the doc went live, the feature had often shipped twice over. The team, ten people building dev tools for distributed apps at Microsoft, decided to fix this not with more headcount but with a tool called GitHub Agentic Workflows, built by the GitHub Next team.

The hard part wasn't writing docs with AI. It was doing it across repositories safely. Aspire's code lives in microsoft/aspire; its docs site, aspire.dev, is a separate repo with its own deploy pipeline and review chain. Handing an AI agent a broad, write-everywhere token was never going to survive a security review, and it shouldn't. GitHub Agentic Workflows solves this with a split design: the agent only reads. It never writes to GitHub directly. Instead it emits a JSON description of what it wants to create, and a separate, narrowly scoped handler executes that intent through a dedicated GitHub App with explicit allow-lists on which repos and branches it can touch.

The resulting pipeline, called pr-docs-check, triggers whenever a pull request merges into main or a release branch. Before the AI does anything, plain bash resolves the correct target branch by checking milestones on the pull request and any linked issues, mapping something like milestone 13.4 straight to release/13.4 on the docs site. Only then does the agent read the diff, decide whether the change needs documentation, draft the content in Aspire's existing MDX style, and hand off a draft pull request — always draft, never merged automatically — assigned to the same engineer who reviewed the original code change.

The numbers, pulled from a 30-day window covering Aspire 13.3 and 13.4, are the real story. Of 396 merged pull requests, the workflow ran on every one and decided only 82 actually needed documentation — correctly, it turns out, since all 82 drafts eventually merged with zero closures and zero stragglers left open. Median time from code merge to docs merge: 44.8 hours, with 96 percent landing within a week. Early on, the agent was too eager, drafting docs for internal CI tweaks and logging refactors, which cost the team a 13 percent closure rate before they tightened the prompt with explicit negative examples. That fix pushed the false-positive rate down and pushed the merge rate to 100 percent.

Beyond the flagship workflow, the team runs three smaller agents: one that maintains a changelog wiki page every two hours, one that updates the support-policy page on stable releases, and one that refreshes integration metadata daily via pnpm. None of it replaces the human writers. It just strips out the reverse-engineering tax so people can spend time on narrative pages and sample code instead of transcribing diffs into reference docs.