Automating cross-repo documentation with GitHub Agentic Workflows
The GitHub Blog
Microsoft's Aspire team built a bot that auto-drafts docs whenever code merges, then routes them to the engineer who shipped the feature for review. It closed the gap between shipping and documenting without adding staff or new process.
Based on reporting by The GitHub Blog — read the original for the full story.
Summary, retelling and take written by AI under human oversight; images are AI-generated illustrations. How we work · Report an error
Nobody likes answering "where are the docs?" On the Aspire team at Microsoft, that question used to trigger a familiar scramble: a writer staring at a closed pull request, trying to reverse-engineer what an engineer built weeks earlier, while that engineer had already moved on to the next thing. The team, which builds dev tools for distributed apps with about 10 people, decided to fix this with GitHub Agentic Workflows, a GitHub Next project that pairs Actions-style automation with an AI model as the worker.
The core problem wasn't writing docs. It was that the product lives in one repo, microsoft/aspire, and the docs live in another, microsoft/aspire.dev. Cross-repo automation is trickier than same-repo automation because it usually means handing out broad, repo-scoped tokens, and any sane security team will veto that. GitHub Agentic Workflows sidesteps this by having the agent never write 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 per-workflow GitHub App with explicit allow-lists.
The team built a workflow called pr-docs-check that fires whenever a pull request merges into main or a release branch. Before any AI touches the problem, plain bash resolves which docs branch the change belongs to, using milestone titles on the pull request or linked issues, mapped to release branches like release/13.4. Only after that does the agent read the diff, decide whether the change needs documentation, and draft the update in the docs repo, tagging the same engineer who reviewed the original feature as the reviewer for the docs pull request. Nothing auto-merges; every draft waits for a human sign-off.
The numbers, pulled from a rolling 30-day window spanning the Aspire 13.3 and 13.4 releases, are the real pitch here. Out of 396 merged pull requests, the workflow ran on all of them but only generated 82 documentation pull requests, correctly deciding most changes, like internal refactors or dependency bumps, needed no docs at all. Every one of those 82 pull requests merged, none closed unmerged, and the median time from code merge to docs merge was 44.8 hours. Nearly all of them, 96%, merged within a week.
It wasn't flawless from day one. An earlier version of the agent's "is this docs-worthy" filter was too generous, drafting docs for things like CI tweaks or logging refactors, and about 13% of an earlier batch of pull requests got closed for that reason. The team tightened the prompt with explicit negative examples and the false-positive rate improved. They also had to solve an awkward cross-repo checkout problem by mirroring the docs repo twice in the same run, and they learned to pre-extract pull request metadata in bash so large diffs didn't blow through the agent's prompt budget.
The security setup is arguably the more interesting part. The agent's GitHub App token is scoped to exactly two repositories, restricted to landing pull requests only on main or release branches, and permanently locked out of files like AGENTS.md and dependency manifests. If a pull request creation fails, the system files an issue instead of dropping the work silently. The team frames this as the real lesson: tight security constraints didn't slow the automation down, they forced a design that ended up more correct.
My take — AI-written commentary, not fact-checked reporting
The headcount-neutral framing is doing a lot of work here, but the more interesting signal is the 100% merge rate on AI-drafted docs paired with an agent that said "no docs needed" over 300 times without anyone auditing each call. That's the actual trust test for agentic automation in production repos, not whether the model can write prose, but whether it knows when to shut up. Teams chasing AI-driven docs or code review should copy the boring part of this setup, the scoped tokens and human-reviewer gate, before they copy the flashy agent part.
Read more about this at: The GitHub Blog