使用 GitHub Agentic Workflows 自动化跨仓库文档

“文档在哪？”这是产品团队中没人喜欢回答的问题。诚实的回答通常是某种形式的“落后了”。一位技术写作者正盯着一份已关闭的拉取请求，试图逆向工程出哪里发生了变化。PR 的作者早已开始下一项工作。等到文档真正发布时，功能早已交付，有时甚至不止一个版本。

前不久，这正是我们 Aspire 团队的写照（我们是一个由 10 人组成的、为分布式应用构建开发工具的小团队）。几个月前，我们试图找出如何安全地将 AI 引入我们已经信任的自动化中。正是在那时，我们发现了 GitHub Agentic Workflows。我开始在 microsoft/aspire 中组装原型。

以下是它给我们带来的成果，数字直接来自 GitHub：在 Aspire 13.3 和 13.4 版本中，82 个功能文档 PR 以中位 44.8 小时的速度合并，每一个都经过了交付该功能的工程师评审。没有增加人头，没有流程重训。只是换了一种方式问“谁来写这个？”。

🔒 约束条件：跨仓库自动化是难点

我们的产品代码在 microsoft/aspire 中，而文档站点在 microsoft/aspire.dev——不同的仓库、部署目标和评审链。大多数团队很快就能搞定同仓库自动化；跨仓库自动化才是真正棘手的地方。范围宽泛的仓库级令牌应该送进博物馆，任何负责任的的安全态势（包括我们的）都会相应地限制它们。这是好事。但如果你写文档的地方不是你写代码的地方，这也会成为真正的瓶颈。

多年来的默认工作流是：

1. 工程师在 microsoft/aspire 中交付一项功能。
2. 文档写作者在数周后注意到。
3. 文档写作者打开 PR，阅读 diff，并 ping 工程师以澄清变更内容。
4. 工程师已在下一个功能上，模糊记得，只回复了部分信息。
5. 文档草稿发布，有时甚至是对着已经发出去的版本。

这就是逆向工程税。我们需要能跨越仓库、同时又不用给代理授予到处写入权限的自动化。GitHub Agentic Workflows 最终被证明是答案。

🤖 为什么选择 GitHub Agentic Workflows

GitHub Agentic Workflows 是由 GitHub Next 团队发起的项目，我总向别人这样形容它：“GitHub Actions，但用模型作为工作项处理器，并带有满足安全审查的护栏。”这么说有点过于简化，但很接近。

它的形态如下：

• 你将工作流编写为一个单独的 Markdown 文件（.github/workflows/my-thing.md）。顶部是 YAML 风格的 frontmatter，下方是一个英文 Prompt。
• 运行 GitHub Agentic Workflows compile 指令，它会生成一个同级的 .lock.yml（普通的 GitHub Actions 工作流），你一并提交。
• 在运行时，工作流会基于你的 Prompt 运行一个代理，该代理的工具集受到约束。
• 至关重要的是，该代理不会直接写入 GitHub。它会发出意图（一个 JSON blob，描述它想创建的 PR、issues 和评论），然后由一个独立的、作用域缩小的作业（safe-outputs 处理器）基于每个工作流的 GitHub App 将意图落地。

最后一点是关键突破。代理只获得读权限和一个 Prompt。写入操作通过一个带有显式允许列表的微小可验证管道进行。安全审查点头。我们就交付。

💚 小插曲：同源的栈

我很喜欢用于构建的工具本身也是用你正在用它们构建的同类工具打造的。GitHub Agentic Workflows 文档 是用 Astro 和 Starlight 构建的。aspire.dev 也是——Astro 配合 Starlight，并借助了更广泛的 Starlight 插件生态（astro-mermaid、starlight-llms-txt、starlight-sidebar-topics、starlight-image-zoom、美观的 @catppuccin/starlight 主题等等。向 Chris Swithinbank 和 Starlight 维护者致敬，整个生态系统感觉是由一群真正在乎的人在精心设计）。

这真是一种亲缘关系。我们用来自动化文档的工具与我们要自动化到的文档站点分享着同样的根基。这很方便，因为下一节中的 Mermaid 序列图在两个世界里渲染出来完全一样。

端到端流水线

这是我们最终采用的流程。主角是一个名为 pr-docs-check.md 的工作流，位于 microsoft/aspire 中。

一次运行由 pull_request: closed 且目标为 main 或 release/* 且 merged == true 的事件触发。从那时开始，工作流会在代理启动之前，先用普通 bash 执行一个确定性的目标分支解析器：

1. PR 里程碑标题（例如 13.4 → aspire.dev 上的 release/13.4）。
2. 链接 Issue 的里程碑标题（从 PR 正文解析 Fixes/Closes/Resolves #N，获取每个 Issue，取第一个非空的里程碑）。
3. PR 的基准分支，如果它匹配 release/X.Y[.Z]。
4. 最后回退到 main。

这是关键所在。产品仓库中的里程碑干净地对应到文档仓库中的发布分支。当代理最终运行时，它确切地知道文档应该落在哪里，无需对目标分支进行任何创造性猜测。

代理读取 diff，扫描链接的 Issues，然后做出决定：这需要文档吗？如果需要，它会在检出的 microsoft/aspire.dev 工作区中，遵循我们已有的文档写作者技能（语气、MDX 约定、Starlight 组件）起草实际内容。然后，它会发出一个 create_pull_request safe-output 并移交。

safe-outputs 处理器接管：

• 标题前缀：[docs]
• 标签：docs-from-code
• draft: true（我们从不自动合并）
• 基准分支：由代理提供，限制为 main 或 release/*
• 目标仓库：microsoft/aspire.dev
• 评审者：从源 PR 的评审中识别出的 SME——即，产品团队信任来批准该功能的人，现在被要求批准该功能的文档。

一个配套作业会在源 PR 上发布一条标记评论，附上文档 PR 的链接，并在重新运行时最小化所有旧的 pr-docs-check 评论。刚刚点击了 Merge 的工程师在几分钟内就会收到通知：“这是文档草稿。审阅一下？”

🔐 safe-outputs 契约

整个安全故事归结为一段短小、枯燥的 frontmatter：

tools: github: toolsets: [repos, issues, pull_requests] min-integrity: approved # 只运行已锁定、经完整性校验的 actions allowed-repos: - microsoft/* github-app: app-id: ${{ secrets.ASPIRE_BOT_APP_ID }} private-key: ${{ secrets.ASPIRE_BOT_PRIVATE_KEY }} owner: "microsoft" repositories: ["aspire.dev", "aspire"]

safe-outputs: create-pull-request: title-prefix: "[docs] " labels: [docs-from-code] draft: true # 人始终在回路中 base-branch: main allowed-base-branches: [main, release/*] target-repo: "microsoft/aspire.dev" protected-files: blocked # AGENTS.md、清单文件、安全配置：禁止触碰 fallback-as-issue: true

契约就这样用明文定义好了。代理获得一个 GitHub App 令牌，其安装作用域正好是两个仓库——产品仓库和文档仓库——组织内的其他任何东西都不可达。它只能在 main 或 release/* 上创建 PR。AGENTS.md 和依赖清单按策略禁止修改。如果 PR 创建失败（网络波动、冲突、任何情况），框架会回退为创建一个 issue，这样什么都不会悄悄丢失。

这正是安全审查真正喜欢的地方。代理的推理是模糊的。但动作面不是。

📊 数据一览

以下数据来自一个滚动的 30 天窗口（2026 年 5 月 3 日至 6 月 2 日），横跨 Aspire 13.3 版本收尾和 13.4 筹备期：

指标	数值
microsoft/aspire 中合并的产品 PR 数	396（338 个 main / 50 个 release/13.3 / 8 个 release/13.2）
pr-docs-check 工作流运行次数	396
在 microsoft/aspire.dev 上创建的文档草稿 PR 数	82
– 已合并	82（100%）
– 未合并关闭	0
– 仍然开放	0
文档 PR 目标分支	52 → release/13.3，27 → release/13.4，3 → main
中位合并用时（文档）	44.8 小时
24 小时内 / 7 天内合并	38% / 96%

注：数据统计于撰写本文时；工作流持续运行，所以总数只会增加。

有几个数字值得再看一遍：

• 396 次运行 → 82 个 PR 不是缺陷。工作流在每个合并的 PR 上运行；其中大部分是内部重构、测试修复或依赖更新，没有面向用户的的改动。代理在 300 多次中说“无需文档”是一个特性。
• 100% 合并率说明代理的文档选择是正确的。我们在 v1 假阳性阶段之后收紧的 Prompt 正在带来回报。

✅ 成功之处，❌ 不足之处

成功之处

• ✅ 里程碑 → 发布分支映射。这是我们做出的杠杆效应最高的单个决策。工程师已经在 PR 和 Issue 上设置里程碑；我们免费获得了准确的目标分支路由。
• ✅ 仅草稿，SME 作为评审者。代理从不合并。交付功能的工程师就是确认文档正确的人。我们已经在文档层面停止了功能的逆向工程。工程师只需在现有位置上告诉文档草稿该说什么。
• ✅ 每个工作流拥有独立、作用域限定的 GitHub App。每个工作流获得自己的 App 令牌，带有明确的仓库和权限范围。安全审查通过了。我们也很满意；第一次需要轮换密钥时就体现出了好处。
• ✅ protected-files: blocked。代理不能触碰 AGENTS.md、包清单或仓库安全配置。绝无例外。

不足之处（起初）

• ❌ 第一版中代理的“这值得写文档吗？”判定门槛过于宽泛。它为真正属于内部的变更创建了草稿 PR，比如 CI 调整或日志重构。结果：69 个 PR 中关闭了 9 个（≈13%），因此我们收紧了 Prompt 中面向用户变更的定义，并添加了明确的负面示例（CI、内部助手、仅测试）。现在，假阳率正趋于下降。
• ❌ 跨仓库 PR 创建需要一个镜像检出模式，这在文档中并不明显。代理在一个仓库中工作；safe-outputs 需要找到目标仓库才能推送分支。我们通过两次检出 microsoft/aspire.dev 来解决——一次作为当前工作区，一次在 _repos/aspire.dev 下——这样 safe-outputs 处理器可以确定性地重新发现它。
• ❌ 过大的 diff 会耗尽 Prompt 预算。我们在 pre-agent-steps bash 中预提取 PR 元数据（链接的 Issue、里程碑、基准分支），这样代理收到的是一个结构化的简短摘要，而不是一个巨大的负载。这是 GitHub Agentic Workflow 的设计模式，行之有效。

总结

我们所做的改变转变了我们的想法。一项功能直到文档完成才算真正完成。文档不再像拴在绳子上的易拉罐一样跟在后面。工程师的评审是闸门；机器人负责打字。

关键的是，这并不会取代文档写作者；它解放了他们。我们的写作者过去将大部分时间花在逆向工程功能上。现在，他们把时间花在只有人才能做好的事情上：叙述性页面、示例项目、概念性导读、文档那些无法从 diff 中自动生成的部分。机器人处理那些机械性的“新增了这个选项；这是参考页面的更新”工作，这类工作对谁来说都不曾有趣。

衷心感谢 GitHub Next 团队提供的 GitHub Agentic Workflows（以及将 safe-outputs 原语作为设计的一等部分），感谢 Chris Swithinbank 和 Starlight 维护者打造了我们自动化进入的文档平台。同样由衷感谢安全团队，他们的防护栏迫使我们从一开始就用正确的方式设计。良好自动化的枯燥秘密就是，强大的安全约束会让系统更可信、更正确。

如果你在一个仓库中构建产品，而在另一个仓库中发布文档——特别是你必须在任何重要的安全边界内这样做——GitHub Agentic Workflows 绝对值得认真审视。从一个工作流开始，比如 pr-docs-check，然后看看你的中位文档时间会发生什么变化。

🔗 其他工作流

pr-docs-check 是我这篇文章所讲述的，但它并非独自运行。如果你对其他的感兴趣，源代码是公开的：

• milestone-changelog.md：每两小时运行一次，获取活跃里程碑中新合并的 PR，并维护一个 13.x 变更日志 Wiki 页面（新功能、改进、值得注意的 Bug 修复），附带一个配套的编辑反馈 Issue。346 次运行。
• release-update-support-mdx.md：在 Aspire 的稳定版本发布时，在 aspire.dev 上起草一个 [support] PR，用于更新支持策略页面（提升新版本，降级前一个版本，刷新“最后更新”徽章）。
• update-integration-data.md：位于文档仓库中；每天运行 pnpm update:all，刷新 NuGet 元数据 + GitHub 统计数据 + 示例数据，并打开一个 chore：Update integration data PR，带有针对过期运行的取代和关闭逻辑。27 次运行，8 个合并的 PR。
• repo-pulse.md：一个滚动的三日仓库仪表盘，固定在一个单独的 Issue 中并就地更新：最近的合并、等待审查的 PR、新建的 Issue、讨论活动。一个 Issue，始终保持更新。

祝自动化愉快，朋友们！🤖🚀

作者

高级软件工程师，Building

“Where are the docs?” It’s a question nobody on a product team enjoys answering. The honest reply is usually some variant of “behind.” 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.

Here’s what that bought us, in numbers pulled straight out of GitHub: for Aspire 13.3 and 13.4, 82 feature-docs pull requests merged at a median of 44.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. Just a different way of asking “who writes this?”

🔒 The constraint: cross-repo automation is the hard part

Our product lives in microsoft/aspire and our docs site lives in microsoft/aspire.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:

1. Engineer ships a feature in microsoft/aspire.
2. Docs writer notices weeks later.
3. Docs writer opens the pull request, reads the diff, and pings the engineer to clarify what changed.
4. Engineer is on the next feature, vaguely remembers, replies with half the picture.
5. 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.

🤖 Why GitHub Agentic Workflows

GitHub Agentic Workflows is a project from the GitHub Next team that I keep describing to people as “GitHub Actions, but with a model as the work-item processor and guard rails that satisfy security review.” That’s reductive, but it’s close.

The shape of it:

• You author a workflow as a single markdown file (.github/workflows/my-thing.md). YAML-style frontmatter on top, an English-language prompt underneath.
• You run GitHub Agentic Workflows compile, and it generates a sibling .lock.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. So is aspire.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. The protagonist is a workflow called pr-docs-check.md living in microsoft/aspire.

A run starts on pull_request: closed against main or release/*, gated by merged == true. From there, the workflow first runs a deterministic target branch resolver in plain bash before the agent ever wakes up:

1. Pull request milestone title (e.g. 13.4 → release/13.4 on aspire.dev).
2. Linked-issue milestone title (parse Fixes/Closes/Resolves #N from the body, fetch each issue, take the first non-empty milestone).
3. Pull request base ref, if it matches release/X.Y[.Z].
4. 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? If yes, it drafts the actual content in a checked-out microsoft/aspire.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.

The safe-outputs handler takes over:

• Title prefix: [docs]
• Label: docs-from-code
• draft: true (we never auto-merge)
• Base branch: agent-supplied, restricted to main or release/*
• Target repo: microsoft/aspire.dev
• Reviewer: the SME identified from the source pull request ’s reviews—i.e., 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. Look it over?”

🔐 The safe-outputs contract

The whole security story comes down to a small, boring stretch of frontmatter:

tools: 
  github: 
    toolsets: [repos, issues, pull_requests] 
    min-integrity: approved          # only run pinned, integrity-checked actions 
    allowed-repos: 
      - microsoft/* 
    github-app: 
      app-id: ${{ secrets.ASPIRE_BOT_APP_ID }} 
      private-key: ${{ secrets.ASPIRE_BOT_PRIVATE_KEY }} 
      owner: "microsoft" 
      repositories: ["aspire.dev", "aspire"] 

safe-outputs: 
  create-pull-request: 
    title-prefix: "[docs] " 
    labels: [docs-from-code] 
    draft: true                      # human-in-the-loop, always 
    base-branch: main 
    allowed-base-branches: [main, release/*] 
    target-repo: "microsoft/aspire.dev" 
    protected-files: blocked         # AGENTS.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/*. AGENTS.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.

📊 By the numbers

Here are the stats from a rolling 30-day window (May 3 – June 2, 2026) spanning the back end of the Aspire 13.3 release and the run-up to 13.4:

Metric	Value
Product pull requests merged in microsoft/aspire	396 (338 main / 50 release/13.3 / 8 release/13.2)
pr-docs-check workflow runs	396
Draft docs pull requests created on microsoft/aspire.dev	82
– Merged	82 (100%)
– Closed without merge	0
– Still open	0
Docs pull requests target branches	52 → release/13.3, 27 → release/13.4, 3 → main
Median time-to-merge (docs)	44.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. The agent cannot touch AGENTS.md, package manifests, or repo security config. Period.

What didn’t (at first)

• ❌ The agent’s “is this docs-worthy?” 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. We solved it by checking out microsoft/aspire.dev twice—once as the current workspace, once under _repos/aspire.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. If you’re curious about the rest, the source is public:

• milestone-changelog.md: runs every two hours, picks up newly merged pull requests in the active milestone, and maintains a 13.x-Change-log wiki page (new features, improvements, notable bug fixes) with a companion editorial-feedback issue. 346 runs.
• release-update-support-mdx.md: on a stable Aspire release, drafts a [support] pull request on aspire.dev that updates the support policy page (promotes the new version, demotes the previous one, refreshes the “Last updated” badge).
• update-integration-data.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.
• repo-pulse.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! 🤖🚀

Written by

Senior Software Engineer, Building aspire.dev at Microsoft

Principal Research Software Design Engineer at Microsoft Research. Creator of MakeCode, GenAIScript and more.