Automating cross-repo documentation with GitHub Agentic Workflows
TL;DR · AI 摘要
Title: Automating cross-repo documentation with GitHub Agentic Workflows URL Source: Published Time: 2026-07-08T14:11:56...
核心要点
- 主题聚焦：Automating cross-repo documentation with GitHub
- 来源：The GitHub Blog，建议结合原文判断细节。
- AI 分析暂不可用，本条为保底评分与摘要。
“文档在哪里？”这是产品团队没人喜欢回答的问题。诚实的回答通常是某种“在后面”的变体。一位作者正盯着一个关闭的拉取请求，试图逆向推导出发生了什么变化。拉取请求的作者早已离开。等文档真正发布时，功能可能已经上线，有时甚至不止一次。
这曾经是我们 Aspire 团队（我们是一个10人小团队，专注于分布式应用开发工具）的处境。几个月前，我们试图探索如何安全地将 AI 引入我们已信任的自动化流程。就在那时，我们发现了 GitHub Agentic Workflows。我开始将原型集成到 microsoft/aspire 中。
以下是 GitHub 提供的数据：对于 Aspire 13.3 和 13.4 版本，82 个功能文档拉取请求在产品拉取请求后的中位数 44.8 小时内合并，每一个都由实现该功能的工程师进行了评审。没有新增人手，无需重新培训流程，只是用不同的方式回答“谁来写这个？”
 约束条件：跨仓库自动化是难点
我们的产品位于 microsoft/aspire，文档站点位于 microsoft/aspire.dev——不同的仓库、不同的部署目标和不同的评审链。大多数团队很快就能解决同仓库自动化的问题；跨仓库自动化才是真正的难点。广域仓库作用域的令牌属于博物馆展品，任何负责任的安全策略（包括我们的）都会相应限制它们。这是好事。但如果写文档的地方不是写代码的地方，这也会成为真正的瓶颈。
多年来默认的工作流程是：
- 工程师在
microsoft/aspire中发布一个功能。 - 文档作者几周后才注意到。
- 文档作者打开拉取请求，阅读差异，然后联系工程师澄清发生了什么变化。
- 工程师正在处理下一个功能，模糊地记得，只回复了部分信息。
- 文档草稿发布时，有时对应的版本早已上线。
这就是“逆向工程税”。我们需要一种无需向代理授予“随处可写”令牌的跨仓库自动化方案。GitHub Agentic Workflows 证明是解决之道。
 为什么选择 GitHub Agentic Workflows
GitHub Agentic Workflows 是 GitHub Next 团队的一个项目，我常向人们描述为“GitHub Actions，但以模型作为工作项处理器，并配有满足安全审查的防护机制”。这种描述有些简化，但已接近本质。
其核心结构如下：
- 您通过一个 单一的 markdown 文件（
.github/workflows/my-thing.md）编写工作流。文件顶部使用 YAML 风格的 frontmatter，下方是英文提示内容。 - 运行 GitHub Agentic Workflows 编译后，会生成一个同级的
.lock.yml文件（一个标准的 GitHub Actions 工作流），您将其提交到版本库中。 - 运行时，工作流会使用受限工具集，让代理程序针对您的提示内容执行操作。
- 关键的是，代理程序不会直接写入 GitHub。它会生成意图（一个描述要创建的拉取请求、问题和评论的 JSON 数据），然后由一个独立且范围狭窄的作业（安全输出处理程序）通过每个工作流专用的 GitHub 应用将意图落地。
最后一项是关键突破点。代理程序获得读取权限和提示内容，所有写入操作都经过一个精简且可验证的流程，并有明确的白名单控制。安全审查通过后，我们即可发布。
 一个补充说明：相似的工具栈
当构建工具本身使用与您构建项目相同的工具时，我总是感到欣喜。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 实现）：
- 从拉取请求的里程碑标题（例如 13.4 → release/13.4 在
aspire.dev上）。 - 从关联问题的里程碑标题（解析正文中的 Fixes/Closes/Resolves #N，获取每个问题，取第一个非空里程碑）。
- 如果拉取请求的基础分支匹配 release/X.Y[.Z]。
- 默认回退到 main 分支。
这是关键环节。产品仓库中的里程碑能清晰映射到文档仓库中的发布分支。当代理程序最终运行时，它能准确知道文档应落地的位置，无需对目标分支进行创造性描述或猜测。
代理程序读取差异内容，扫描关联问题，判断是否需要文档。如果需要，它会在已检出的 microsoft/aspire.dev 工作区中，按照我们现有的文档编写规范（语调、MDX 格式、Starlight 组件）起草实际内容。然后生成 create_pull_request 安全输出并移交处理。
安全输出处理程序接管后续流程：
- 标题前缀: [docs]
- 标签: docs-from-code
- 草稿: true (我们从不自动合并)
- 基础分支: 由代理提供，限制为
main或release/* - 目标仓库:
microsoft/aspire.dev - 审查者: 来自源拉取请求审查中识别出的领域专家——即产品团队信任批准该功能的人，现在会被要求批准该功能的文档。
配套任务会在源拉取请求上发布一个标记评论，包含文档拉取请求链接，并在重新运行时最小化任何旧的 pr-docs-check 评论。刚刚点击 Merge 的工程师会在几分钟内收到通知：“这是文档草稿。请过目？”
 安全输出契约
整个安全机制归结为一段平淡无奇的前置信息：
tools:
github:
toolsets: [repos, issues, pull_requests]
min-integrity: approved # 仅运行固定且经过完整性检查的操作
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应用令牌，其安装范围严格限定在恰好两个仓库——产品仓库和文档仓库——组织中的其他内容均无法访问。它只能针对 main 或 release/* 分支创建拉取请求。AGENTS.md 和依赖清单根据政策被禁止访问。如果拉取请求创建失败（网络波动、冲突等），框架会回退为创建问题，确保不会静默丢弃任何内容。
这是安全审查真正认可的部分。代理的推理是模糊的，但操作界面却是明确的。
 数据统计
以下是滚动30天窗口（2026年5月3日–6月2日）的统计数据，涵盖Aspire 13.3版本发布后期和13.4版本发布前的阶段：
| 指标 | 数值 | | --- | --- | | 在 microsoft/aspire 中合并的产品拉取请求 | 396（338个 main / 50个 release/13.3 / 8个 release/13.2） | | pr-docs-check 工作流运行次数 | 396 | | 在 microsoft/aspire.dev 上创建的文档草稿拉取请求 | 82 | | – 已合并 | 82（100%） | | – 未合并关闭 | 0 | | – 仍开放 | 0 | | 文档拉取请求目标分支 | 52→release/13.3, 27→release/13.4, 3→main | | 文档合并中位时间 | 44.8 小时 | | 24小时内/7天内合并比例 | 38% / 96% |
_注: \_数据为撰写时捕获，工作流仍在持续运行，因此总数只会增加。_
这些数据中有一些特别值得关注：
- 396 次运行 → 82 个拉取请求并不是缺陷。该工作流会在每个合并的拉取请求上运行；其中大部分是内部重构、测试修复或依赖项升级，没有用户可见的表面变化。代理说“不需要文档”300 多次是功能特性。
- 100% 合并率表明代理的文档选择是正确的。我们在 v1 版本误报阶段之后发布的更严格的提示词正在产生效果。
 成功之处，**** 不足之处
成功之处
不足之处（最初）
代理最初的“是否需要文档？”判断过于宽松。它为真正内部的更改（如 CI 调整或日志重构）创建了拉取请求。结果：69 个拉取请求中有 9 个被关闭（≈13%），所以我们收紧了提示词中“用户可见更改”的定义，并添加了明确的负面示例（CI、内部辅助工具、仅测试）。现在，这一比例正在下降。- 跨仓库创建拉取请求需要一个镜像检出模式，这在文档中并不明显。代理在一个仓库中运行；safe-outputs 需要找到目标仓库以推送分支。我们通过两次检出
microsoft/aspire.dev解决了这个问题——一次作为当前工作区，另一次作为under_repos/aspire.dev——这样 safe-outputs 处理器可以确定性地重新发现它。 - 大规模差异会消耗提示词预算。我们在代理运行前的 bash 脚本中预先提取拉取请求元数据（关联问题、里程碑、基准引用），这样代理可以接收到一个小型的结构化摘要，而不是庞大的负载。这是 GitHub Agentic Workflow 的设计模式，且效果良好。
总结
我们所做的更改改变了我们的思维方式。一个功能只有在文档完成之后才被视为完成。文档不再像系在绳子上的罐头一样拖在功能后面。工程师的审核是关卡；机器人负责打字。
关键的是，这并没有取代文档撰写者；它减轻了他们的负担。我们的撰写者过去大部分时间都花在反向工程功能上。现在，他们可以专注于只有人类才能做好之事：叙事页面、示例程序、概念性引导，以及那些不会从差异中自然产生的文档部分。机器人处理的是机械性工作：“新增了这个选项；这里是参考页面更新”，这种工作从未让人感到愉快。
感谢 GitHub Next 团队开发的 GitHub Agentic Workflows（以及将 safe-outputs 原语作为设计核心部分），感谢 Chris Swithinbank 和 Starlight 维护者为我们构建了自动化的文档平台。同时也要真诚感谢安全团队，他们的防护措施迫使我们第一次就正确地设计了这个系统。优秀自动化的一个无聊但重要的秘密是：强大的安全限制会使系统更加可信且更正确。
如果你在一个仓库中构建产品，而在另一个仓库中发布文档——尤其是当你必须在任何非平凡的安全边界内完成此操作时——GitHub Agentic Workflows 值得认真考虑。从一个工作流（例如 pr-docs-check）开始，观察你的文档平均耗时会发生什么变化。
 其他工作流
/think
pr-docs-check 就是我在本文中提到的脚本，但它并非独立运行。如果你对其他脚本感兴趣，源代码是公开的：
milestone-changelog.md：每两小时运行一次，抓取活跃里程碑中新合并的拉取请求，并维护一个 13.x-Change-log 维基页面（包含新功能、改进、重要错误修复），同时配合一个编辑反馈问题。已运行 346 次。release-update-support-mdx.md：在稳定版 Aspire 发布时，于aspire.dev上创建一个 [支持] 拉取请求，更新支持政策页面（推广新版本、降级旧版本、刷新“最后更新”徽章）。update-integration-data.md：位于文档仓库中；每天运行pnpm update:all，刷新 NuGet 元数据 + GitHub 统计数据 + 示例数据，并创建一个chore: Update integration data拉取请求，对过期运行使用覆盖并关闭逻辑。已运行 27 次，8 次合并。repo-pulse.md：一个滚动的三天仓库仪表板，固定在单个问题中并原地更新：最近的合并、等待审核的拉取请求、新问题、讨论活动。一个问题，始终保持最新。
祝你自动化愉快！ 
- * *
标签：
作者
微软公司高级软件工程师，负责构建 aspire.dev
微软研究院首席研究软件设计工程师，MakeCode、GenAIScript 等工具的创建者。
在 GitHub 上探索更多
文档
一站式掌握 GitHub 所有内容的必备资源。
GitHub
在 GitHub 上构建未来，这里是任何人都能构建任何事物的平台。
客户案例
了解使用 GitHub 构建产品的公司和工程团队。
GitHub Universe 2026
10 月 28-29 日，加入我们在旧金山或在线举办的 GitHub Universe，这是我们的旗舰开发者大会，汇聚人、代理和全球代码。