Automating cross-repo documentation with GitHub Agentic Workflows

” It’s a question nobody on a product team enjoys answering. ” A writer is staring at a closed pull request, trying to reverse-engineer what changed. The pull request’s author has already moved on.

By the time the doc actually publishes, the feature has shipped, sometimes more than once. That used to be us on the Aspire team (we’re a small team of 10 building dev tools for distributed apps). A few months back, we were trying to figure out how to safely bring AI into automations we already trusted.

That’s when we discovered GitHub Agentic Workflows. I started bolting prototypes into microsoft/aspire . 8 hours after the product pull request , every one of them reviewed by the engineer who shipped the feature.

No new headcount. No process retraining. dev —different repo, deploy target, and review chain.

Most teams figure out same-repo automation pretty quickly; cross-repo automation is where things get sharp. Broad repo-scoped tokens belong in a museum, and any responsible security posture (ours included) restricts them accordingly. That’s a good thing.

It’s also a real bottleneck if the place where you write the docs isn’t the place where you write the code. The default workflow for years was: Engineer ships a feature in microsoft/aspire . Docs writer notices weeks later.

Docs writer opens the pull request, reads the diff, and pings the engineer to clarify what changed. Engineer is on the next feature, vaguely remembers, replies with half the picture. Docs draft ships, sometimes against a release that’s already out.

This is the reverse-engineering tax. We needed automation that crossed repos without handing an agent a write-everywhere token. GitHub Agentic Workflows turned out to be the answer.

” That’s reductive, but it’s close. md ). YAML-style frontmatter on top, an English-language prompt underneath.

yml (a normal GitHub Actions workflow) that you commit alongside. At runtime, the workflow runs an agent against your prompt with a constrained toolset. Critically, the agent doesn’t write to GitHub directly .

It emits intent (a JSON blob describing the pull requests, issues, and comments it wants to create), and a separate, narrowly scoped job (the safe-outputs handler ) materializes that intent against a per-workflow GitHub app. That last bullet is the unlock. The agent gets read access and a prompt.

Writes go through a tiny verifiable pipeline with explicit allow-lists. Security review nods. We ship.

💚 A small aside: kindred stacks I love when the tools you’re using to build are built with the same tools you’re using to build with. The GitHub Agentic Workflows docs are built with Astro and Starlight. dev—Astro with Starlight, dressed up with the wider Starlight plugin ecosystem (astro-mermaid, starlight-llms-txt, starlight-sidebar-topics, starlight-image-zoom, the gorgeous @catppuccin/starlight theme, and more.

Shout-out to Chris Swithinbank and the Starlight maintainers, the entire ecosystem feels designed by people who genuinely care). There’s a real kinship there. The tool we use to automate docs and the docs site we automate into share the same foundation.

Convenient, because the Mermaid sequence diagram in the next section renders the exact same way in both worlds. The end-to-end pipeline Here’s the flow we landed on. md living in microsoft/aspire .

A run starts on pull_request: closed against main or release/* , gated by merged == true . g. dev ).

Linked-issue milestone title (parse Fixes/Closes/Resolves #N from the body, fetch each issue, take the first non-empty milestone). Z]. Fall back to main.

This is the linchpin. Milestones in the product repo map cleanly to release branches in the docs repo. When the agent finally runs, it knows exactly where the docs should land without any creative writing about target branches or guessing.

The agent reads the diff, scans linked issues, and decides: does this need docs? dev workspace, following our existing doc-writer skill (voice, MDX conventions, Starlight components). It then emits a create_pull_request safe-output and hands off.

, whoever the product team trusted to approve the feature, now gets asked to approve the doc for that feature. A companion job posts a marker comment back on the source pull request with the docs pull request link and minimizes any older pr-docs-check comments on re-run. The engineer who just hit Merge gets a notification within a few minutes: “Here’s the docs draft.

md, manifests, security config: hands off fallback-as-issue: true That’s the deal in plain text. The agent gets a GitHub App token whose installation is scoped to exactly two repositories —the product repo and the docs repo—and nothing else in the org is reachable. It can only land pull requests against main or release/* .

md and dependency manifests are off-limits by policy. If the pull request creation fails (network blip, conflict, anything), the framework falls back to filing an issue, so nothing is silently dropped. This is the part security review actually liked.

The agent’s reasoning is fuzzy. The action surface is not. 8 hours  Merged within 24 h / 7 days  38% / 96%  Note: Numbers captured at the time of writing; the workflows keep running, so the totals only go up.

  A few of those numbers deserve a second look: 396 runs → 82 pull requests is not a defect. The workflow runs on every merged pull request; most of them are internal refactors, test fixes, or dependency bumps with no user-facing surface. The agent saying “no docs needed” 300+ times is a feature.

100% merge rate says the agent’s docs picks are right. The tighter prompt we shipped after the v1 false-positive phase is paying off. ✅ What worked, ❌ what didn ’ t What worked ✅ Milestone → release-branch mapping.

This was the single highest-leverage choice we made. Engineers already set milestones on pull requests and issues; we got accurate target-branch routing for free. ✅ Draft-only, SME-as-reviewer .

The agent never merges. The engineer who shipped the feature is the one who confirms the docs are right. We’ve stopped reverse-engineering features at the doc layer.

The engineer just tells the docs draft what to say, in the place where they already are. ✅ Scoped GitHub app per workflow . Each workflow gets its own app token with explicit repo and permission scopes.

Security review approved. We approved too; the first time we needed to rotate keys. ✅ protected-files: blocked .

md , package manifests, or repo security config. Period. ” gate was too generous in the first version.

It drafted pull requests for changes that were genuinely internal, such as a CI tweak or a logging refactor. The result: 9 closures of 69 pull requests (≈13%), so we tightened the prompt’s user-facing-change definition and added explicit negative examples (CI, internal helpers, tests-only). Now, the rate is trending down.

❌ Cross-repo pull request creation needed a mirrored checkout pattern that wasn’t obvious from the docs. The agent works in one repo; safe-outputs needs to find the target repo to push a branch. dev —so the safe-outputs handler can rediscover it deterministically.

❌ Big diffs blow prompt budgets. We pre-extract pull request metadata (linked issues, milestone, base ref) in pre-agent-steps bash, so the agent gets a small, structured summary instead of a giant payload. This is GitHub Agentic Workflow’s designed-in pattern, and it works.

Wrapping up The changes we made shifted our thinking. A feature wasn’t considered done until the docs were. Docs no longer trail along behind it like a tin can on a string.

The engineer’s review is the gate; the bot does the typing. Critically, this doesn’t replace docs writers ; it un-burdens them. Our writers used to spend most of their time reverse-engineering features.

Now they spend their time on the things only a human can do well: narrative pages, sample programs, conceptual walkthroughs, the parts of the docs that don’t fall out of a diff. The bot handles the mechanical “this new option was added; here’s the reference page update” work that was never enjoyable for anyone. Huge thanks to the GitHub Next team for GitHub Agentic Workflows (and for making the safe-outputs primitive a first-class part of the design), and to Chris Swithinbank and the Starlight maintainers for the docs platform we automate into.

A genuine thank-you, too, to the security folks whose guardrails forced us to design this the right way the first time. The boring secret of good automation is that strong security constraints make the system more trustworthy and more correct. If you build a product in one repo and ship docs in another—and especially if you have to do it inside any nontrivial security boundary—GitHub Agentic Workflows is worth a serious look.

Start with one workflow, such as pr-docs-check , and watch what happens to your median time-to-docs. 🔗 The other workflows pr-docs-check is the one I wrote this post about, but it’s not running alone. x-Change-log wiki page (new features, improvements, notable bug fixes) with a companion editorial-feedback issue.

346 runs. dev that updates the support policy page (promotes the new version, demotes the previous one, refreshes the “Last updated” badge). md : lives in the docs repo; runs pnpm update:all daily, refreshes NuGet metadata + GitHub stats + sample data, and opens a chore: Update integration data PR with supersede-and-close logic for stale runs.

27 runs, eight merged pull requests. md : a rolling three-day repo dashboard pinned to a single issue and updated in place: recent merges, pull requests awaiting review, new issues, discussion activity. One issue, always fresh.

Happy automating, friends! 🤖🚀 The post Automating cross-repo documentation with GitHub Agentic Workflows appeared first on The GitHub Blog .