Automating Cross-Repo Documentation with GitHub Agentic Workflows

Automating Cross-Repo Documentation with GitHub Agentic Workflows

Documentation is the unsung hero of any software project, but keeping it up-to-date can be a nightmare. For the Aspire team at Microsoft, the question "Where are the docs?" was often met with silence or frustration. Engineers would move on to new tasks, leaving writers to reverse-engineer changes from closed pull requests. The result? Documentation that lagged behind features, sometimes by weeks or even months.

But that all changed when the team discovered GitHub Agentic Workflows. This tool transformed their documentation process, making it faster, more accurate, and secure. Let’s dive into how they did it and why it matters for anyone building software across multiple repositories.

The Problem: Cross-Repo Documentation Chaos

The Aspire team faced a common challenge: their product code lived in one repository (microsoft/aspire), while their documentation resided in another (microsoft/aspire.dev). This separation created a bottleneck. Engineers would ship features, but the documentation writers wouldn’t notice until weeks later. By the time the docs were ready, the feature had already shipped—sometimes more than once.

The default workflow was inefficient:

1. An engineer ships a feature.
2. A docs writer notices the change weeks later.
3. The writer opens a pull request, reads the diff, and pings the engineer for clarification.
4. The engineer, already focused on the next feature, vaguely remembers the details.
5. The docs draft ships, often against a release that’s already out.

This process was slow, error-prone, and frustrating for everyone involved. The team needed a way to automate documentation across repositories without compromising security. Enter GitHub Agentic Workflows.

What Is GitHub Agentic Workflows?

GitHub Agentic Workflows is a project from the GitHub Next team that combines the power of GitHub Actions with AI-driven automation. It allows you to define workflows in a single markdown file, which generates a corresponding GitHub Actions workflow. At runtime, the workflow runs an agent that processes prompts and emits intent (e.g., pull requests, issues) through a secure, narrowly scoped pipeline.

Here’s how it works:

1. You author a workflow in a .md file with YAML-style frontmatter and an English-language prompt.
2. The workflow compiles into a .lock.yml file, which is a standard GitHub Actions workflow.
3. At runtime, the agent processes the prompt and emits intent, which is then materialized by a separate, secure job.

The key feature is the safe-outputs handler. This ensures that the agent only performs actions within explicitly defined constraints, such as writing to specific branches or repositories. This satisfies security requirements without sacrificing functionality.

The Solution: Automating Documentation Across Repos

The Aspire team created a workflow called pr-docs-check.md to automate documentation updates. Here’s how it works:

1. The workflow triggers on pull_request: closed events for the main or release/* branches.
2. It resolves the target branch by checking the pull request milestone, linked issues, or base ref.
3. The agent reads the diff, scans linked issues, and decides if documentation is needed.
4. If yes, it drafts the documentation content in a checked-out microsoft/aspire.dev workspace.
5. The safe-outputs handler creates a draft pull request in the docs repo, assigns the engineer who approved the feature as a reviewer, and notifies them.

This process ensures that documentation is created or updated shortly after a feature is merged, with the engineer’s review ensuring accuracy.

The Results: Faster, More Accurate Documentation

The numbers speak for themselves. In a 30-day window:

• 396 product pull requests merged in microsoft/aspire.
• 82 draft docs pull requests created in microsoft/aspire.dev, all of which were merged.
• Median time-to-merge for docs: 44.8 hours, with 38% merged within 24 hours and 96% within 7 days.

This is a significant improvement over the previous manual process, where documentation often lagged by weeks or months.

What Worked (and What Didn’t)

The team identified several key success factors:

• Milestone → release-branch mapping: Engineers already set milestones, so this provided accurate target-branch routing.
• Draft-only, SME-as-reviewer: The engineer who shipped the feature reviews the docs, ensuring accuracy.
• Scoped GitHub app per workflow: Each workflow has its own app token with explicit permissions, satisfying security requirements.

However, there were challenges:

• The agent’s initial "docs-worthy" gate was too generous, creating pull requests for internal changes. This was fixed by tightening the prompt.
• Cross-repo pull request creation required a mirrored checkout pattern, which wasn’t obvious from the docs.
• Large diffs blew prompt budgets, which was mitigated by pre-extracting metadata.

The Bigger Picture: Unburdening Docs Writers

GitHub Agentic Workflows doesn’t replace documentation writers; it unburdens them. Writers no longer spend time reverse-engineering features. Instead, they focus on higher-value tasks like narrative pages, sample programs, and conceptual walkthroughs. The bot handles the mechanical updates, freeing up human creativity for more impactful work.

Wrapping Up

GitHub Agentic Workflows has transformed the Aspire team’s documentation process, making it faster, more accurate, and secure. If you’re building a product in one repo and shipping docs in another, this tool is worth a serious look. Start small, automate one workflow, and watch your median time-to-docs shrink.

Happy automating, friends! 🤖🚀