Docs that track the code, not the other way around

Every product team knows the drill: an engineer merges a feature, a writer notices weeks later, and a reverse-engineering session follows to reconstruct what actually changed. For the Aspire team at Microsoft, this lag was chronic—until they turned the problem over to an autonomous workflow.

The team behind aspire.dev runs a small shop of ten people building dev tools for distributed applications. Their docs live in a different repository than their code, with separate deploy targets and review chains. When they wanted to close the gap between code merging and documentation shipping, they found GitHub Agentic Workflows—a tool from the GitHub Next team that pairs the reasoning capabilities of a model with the guardrails of a formal action pipeline.

Why cross-repo automation is uniquely hard

Most teams can automate documentation within a single repository without much friction. The challenge escalates when the code lands in microsoft/aspire and the docs require a pull request in microsoft/aspire.dev. Broad repository-scoped tokens are a security liability, and most responsible organizations—Aspire included—restrict them heavily. The result is a documentation process that typically looks like this:

  1. An engineer merges a feature into microsoft/aspire.
  2. A documentation writer eventually takes notice and opens a draft based on the diff.
  3. The writer pings the engineer for clarification on what actually changed.
  4. The engineer, now focused on another task, offers an incomplete recollection.
  5. The docs ship—sometimes after the release they were meant to accompany.

GitHub Agentic Workflows offered a different path. Instead of handing an agent write access everywhere, the design separates thinking from acting: the agent proposes changes, and a narrow, verifiable safe-outputs handler executes them with explicit allow-lists.

How the architecture separates thinking from acting

The heart of GitHub Agentic Workflows is a workflow defined as a single markdown file, such as .github/workflows/pr-docs-check.md, with YAML frontmatter on top and a plain-English prompt underneath. Compiling this file produces a sibling .lock.yml—an ordinary GitHub Actions workflow committed to the repository. At runtime, the agent works against a constrained toolset, but never writes directly to GitHub. Instead, it emits a structured JSON intent describing the pull requests, issues, or comments it wishes to create. A separate safe-outputs handler inspects that intent and materializes it against a per-workflow GitHub App.

The agent operates with read access only. All writes pass through a pipeline with explicit restrictions, which is precisely what makes the system palatable to security review. The agent’s reasoning may be open-ended, but the action surface it can touch is firmly bounded.

The docs-generation pipeline

The main workflow, pr-docs-check.md, runs in the product repository and takes over on pull request closure

A run triggers on pull_request: closed against main or release/*, gated on merged == true. Before the agent wakes up, a deterministic bash resolver determines the target documentation branch:

  1. The pull request’s milestone title—13.4 becomes release/13.4 on aspire.dev.
  2. The milestone title of any linked issue referenced via Fixes/Closes/Resolves patterns in the pull request body.
  3. The pull request’s base ref, when it matches release/X.Y[.Z].
  4. Fall back to main.

This mapping between product milestones and docs release branches proved to be the linchpin. Engineers already tag their work with milestone titles, so the routing logic comes free of extra ceremony.

Once the target branch is known, the agent examines the diff and related issues to determine if user-facing documentation is required. If so, it drafts content inside a checked-out copy of microsoft/aspire.dev, following a predefined doc-writer skill that encodes the project’s voice and conventions. The agent then emits a create_pull_request safe-output. The safe-outputs handler applies the guardrails:

  • Title prefix: [docs]
  • Label: docs-from-code
  • Draft status: true—never merged automatically
  • Base branch limited to main or release/*
  • Target repository: microsoft/aspire.dev
  • Reviewer: the engineer who approved the original pull request—the subject-matter expert most equipped to validate the documentation

A companion job posts the docs pull request link back on the source pull request and tidies older pr-docs-check comments. The engineer who merged the feature receives a notification minutes later with a ready-to-review draft.

A security model built on restriction

The entire security stance collapses into a concise frontmatter block that reads like a plain-English agreement: the agent gets a token scoped to exactly two repositories (product and docs), can only open pull requests against approved branches, and cannot touch sensitive files like AGENTS.md or dependency manifests. Should pull request creation fail from a network glitch or conflict, the framework files an issue instead—so nothing disappears silently.

Measured results from a 30-day window

Across a rolling month from May 3 through June 2, 2026, spanning the tail end of the 13.3 release and the lead-up to 13.4, the workflow merged 82 feature-docs pull requests at a median of 44.8 hours after the source pull request. Every draft went through the engineer who owned the feature.

A few numbers put this in proportion. The workflow ran 396 times, but most merged pull requests were internal refactors, dependency bumps, or test-only changes. The agent correctly concluded that no docs were needed on over 300 runs—the quiet rejections are as valuable as the drafts. A 100% merge rate indicates the agent’s judgment about what warranted documentation aligned closely with what engineers accepted.

What worked, and what needed adjustment

The milestone-to-branch routing deserves top billing—it delivered accurate targeting without extra process. Draft-only pull requests assigned to the original feature reviewer meant the engineer who merged a feature also confirmed its documentation. Per-workflow GitHub App tokens with tightly scoped permissions satisfied both security review and operational rotation needs. Protected files remained blocked outright: no agent can touch AGENTS.md, package manifests, or security configuration.

The early experience wasn’t entirely smooth. The initial version of the workflow was over-eager in deciding what required documentation, drafting pull requests for CI adjustments and internal logging refactors. Nine of the first 69 open pull requests were closed—roughly 13%. Adding explicit negative examples to the prompt, such as internal helpers and tests-only changes, drove the false-positive rate down.

Two technical hurdles emerged. Creating a cross-repo pull request required the safe-outputs handler to locate the target repository; checking out microsoft/aspire.dev under a predictable path like _repos/aspire.dev solved it. Big diffs also threatened to exhaust prompt budgets, so the team pre-extracted structured metadata—linked issues, milestones, base branch—in deterministic bash steps, feeding the agent a compressed summary instead of the full pull request payload.

## Beyond the flagship workflow pr-docs-check runs alongside several companion automations, all public in the Aspire repositories:

  • milestone-changelog.md: every two hours, it sweeps newly merged pull requests in the active milestone and maintains a release changelog wiki page with an editorial-feedback issue. Over the measured period it logged 346 runs.
  • release-update-support-mdx.md: on a stable release, drafts a pull request on aspire.dev updating the support policy page—promoting the new version, retiring the previous one, and refreshing the availability badge.
  • update-integration-data.md: runs daily in the docs repo, refreshing NuGet metadata and GitHub statistics for integration pages, then opens a chore pull request that supersedes previous stale runs—27 runs, eight merged.
  • repo-pulse.md: maintains a rolling three-day activity dashboard in a single issue—recent merges, waiting reviews, fresh issues, discussion activity—kept current automatically.

The writers still handle the pages a machine can’t author well—narrative guides, sample applications, conceptual explanations. The automation absorbs what was always mechanical drudgery: reference updates that fall directly out of a diff. An engineer’s review remains the gate; the bot does the typing.