GitHub Agentic Workflows: Automating Cross-Repo Documentation at Scale

Thu, 09 Jul 2026 00:00:00 +0000

Closing the Gap Between Code Merge and Docs Ship

“Where are the docs?” It is a question that haunts product teams everywhere. Documentation consistently lags behind feature releases — not from lack of effort, but from process friction. A feature ships in one repository, weeks pass, a writer reverse-engineers the diff, the engineer has already moved on, and the docs finally land against a release that is already live.

The Microsoft Aspire team — a small group building dev tools for distributed apps — decided to treat this as a solvable engineering problem. In a detailed post on the GitHub Blog, engineers David Pine and Peli de Halleux shared how they automated cross-repo documentation using GitHub Agentic Workflows.

The Cross-Repo Problem

The Aspire product lives in microsoft/aspire while its documentation lives in microsoft/aspire.dev — different repos, deploy targets, and review chains. Cross-repo automation is where security review gets nervous and workflows stall. The old process was painful: engineer ships a feature, writer notices weeks later, opens a PR, reverse-engineers the diff, pings the engineer who half-remembers, and the docs ship late — sometimes after the release.

How Agentic Workflows Works

GitHub Agentic Workflows, from the GitHub Next team, is described by Pine as “GitHub Actions, but with a model as the work-item processor and guard rails that satisfy security review.” Workflows are authored as single markdown files (.github/workflows/my-thing.md) with YAML-style frontmatter and an English-language prompt. At runtime, the agent runs against the prompt with a constrained toolset. Critically, the agent does not write to GitHub directly — it emits JSON “intent,” and a separate “safe-outputs handler” materializes that intent against a per-workflow GitHub App. The agent gets read access and a prompt; writes go through a tiny verifiable pipeline with explicit allow-lists.

Results That Speak

For Aspire 13.3 and 13.4, the results are striking:

82 feature-docs pull requests merged at a median of 44.8 hours after the product PR
100% merge rate — every draft the agent created was eventually merged
38% merged within 24 hours, 96% within 7 days
The agent correctly determined that over 300 of 396 merged PRs needed no docs at all

Each workflow runs on every merged pull request, reads the diff and linked issues, decides whether docs are needed, and drafts the actual content. The engineer who shipped the feature is automatically tagged as the reviewer.

A Smarter Security Model

Each workflow gets its own GitHub App token scoped to exactly two repositories. Pull requests can only land against main or release/* branches. Protected files like security config are off-limits by policy. The framework even falls back to filing an issue if PR creation fails — nothing is silently dropped.

What This Means

The bot handles the mechanical work — “this option was added, here’s the reference update” — while human writers focus on narrative pages, conceptual walkthroughs, and the parts of documentation that require genuine understanding. As Pine puts it: “The boring secret of good automation is that strong security constraints make the system more trustworthy and more correct.”

The full source for the pr-docs-check workflow and companion automations is publicly available. For teams shipping products in one repo and docs in another, GitHub Agentic Workflows offers a proven, security-reviewed path to closing the documentation gap.