［開発者向け］GitHubのAspireチームが実践する「機能とドキュメントを同時に完成させる」自動化ワークフロー

2026-07-12

はじめに

　GitHubが2026年7月8日、社内のAspireチームの事例として、GitHub Agentic Workflowsを使ったドキュメント自動生成の実践方法を公開しました。本稿では、コード変更を検知してドキュメント草稿を自動作成する仕組みと、その運用実績について解説します。

参考記事

タイトル: Automating cross-repo documentation with GitHub Agentic Workflows
著者: David Pine, Peli de Halleux
発行元: GitHub Blog
発行日: 2026年7月8日
URL: https://github.blog/ai-and-ml/github-copilot/automating-cross-repo-documentation-with-github-agentic-workflows/

要点

Microsoftの開発ツールチームであるAspireは、GitHub Agentic Workflowsを用いて、機能追加のプルリクエストがマージされると自動的にドキュメント草稿のプルリクエストを作成する仕組みを構築している。
ワークフローはエージェントが起動する前に、マイルストーン情報をもとにリリースブランチを機械的に解決する処理を行う。
エージェントはGitHubへの直接的な書き込み権限を持たず、「安全な出力(safe-outputs)」の仕組みを通じて、スコープを限定したGitHub Appがプルリクエストを作成する。
2026年5月3日から6月2日までの30日間で、396件の製品プルリクエストに対しワークフローが実行され、82件のドキュメント草稿プルリクエストが作成され、すべてがマージされた。
ドキュメント草稿のマージまでの時間の中央値は44.8時間であり、96%が7日以内にマージされている。

詳細解説

クロスリポジトリ自動化という壁

　Aspireチームは、製品コードをmicrosoft/aspireリポジトリで、ドキュメントサイトをmicrosoft/aspire.devリポジトリでそれぞれ管理しています。GitHubによれば、従来はエンジニアが機能を実装してから数週間後にドキュメント担当者が変更に気づき、プルリクエストの差分を読み解いたうえでエンジニアに確認するという「後追い」の運用が続いていたとのことです。

　同一リポジトリ内での自動化に比べ、異なるリポジトリをまたぐ自動化は難易度が上がります。 広範なスコープ のトークンをエージェントに渡すことはセキュリティ上望ましくなく、書き込み権限を安易に付与できない点が長年のボトルネックだったと考えられます。

GitHub Agentic Workflowsの仕組み

　2026年3月に発表されたGitHub Agentic Workflowsは、GitHub Nextチームが開発した仕組みで、ワークフローをMarkdownファイル(.github/workflows/*.md)として記述します。これをコンパイルすると、通常のGitHub Actionsワークフローファイル(.lock.yml)が生成される仕組みです。実行時には、指定されたツールセットの範囲内でエージェントがプロンプトに従って動作します。

　ここで重要なのは、エージェントが直接GitHubに書き込むのではなく、作成したいプルリクエストやコメントの内容をJSON形式の「意図」として出力する点です。その意図を、スコープを限定した別のジョブ(safe-outputsハンドラー)が、ワークフローごとに発行されたGitHub Appを通じて実際の操作に変換します。エージェントの判断はあいまいさを含んでいても、実行できる操作の範囲自体は明確に絞り込まれる設計だと言えます。

pr-docs-checkの処理フロー

　中心となるワークフローは pr-docs-check.md という名称で、microsoft/aspireリポジトリのプルリクエストがマージされると起動します。エージェントが動き出す前に、まずbashスクリプトがプルリクエストのマイルストーン(例:「13.4」)や、本文に記載されたリンク先issueのマイルストーンなどをもとに、ターゲットとなるリリースブランチを機械的に決定します。

　ターゲットブランチが確定すると、エージェントは差分とissueを読み、ドキュメントが必要かどうかを判断します。必要と判断した場合は、microsoft/aspire.devのワークスペース内で既存のドキュメント執筆スキル(文体やMDXの慣習)に従って草稿を作成し、プルリクエスト作成の「意図」を出力します。safe-outputsハンドラーはこの意図をもとにdraftプルリクエストを作成し、元のプルリクエストをレビューしたエンジニア自身をレビュアーとして指定します。

安全性を担保する「セーフアウトプット」

　GitHubの発表では、ワークフローの設定において、GitHub Appのインストール先を製品リポジトリとドキュメントリポジトリの2つだけに限定し、対象ブランチも main と release/* のみに制限しているとのことです。AGENTS.mdや依存関係の設定ファイルなど、セキュリティに関わるファイルへの変更は明示的にブロックされています。プルリクエストの作成に失敗した場合には、issueとして起票するフォールバックも用意されているとのことです。

　この設計により、行動範囲そのものが最初から限定されることになります。セキュリティレビューを通過しやすい理由は、エージェントの判断力そのものではなく、この「実行できる操作の限定」にあると考えられます。

30日間の実績

　GitHubによれば、2026年5月3日から6月2日までの30日間で、microsoft/aspireでは396件のプルリクエストがマージされ、これに対応する形でpr-docs-checkが396回実行されました。このうち82件でドキュメント草稿のプルリクエストが作成され、すべてがマージされ、マージされずにクローズされたものや未処理のまま残ったものはなかったとのことです。マージまでの時間の中央値は44.8時間、24時間以内にマージされた割合は38%、7日以内では96%に達したと報告されています。

　396回の実行に対して草稿作成に至ったのは82件のみですが、GitHubは、内部的なリファクタリングやテスト修正などユーザーに影響しない変更ではエージェントが「ドキュメント不要」と判断しているためだと説明しています。むやみに草稿を量産しないという判断も、運用上は精度の高さを示す要素だと言えそうです。

うまくいった点・つまずいた点

　うまくいった点として、マイルストーンとリリースブランチの対応付け、ドラフトPRとSME(領域の専門知識を持つ人物)によるレビューの組み合わせ、ワークフローごとにスコープを限定したGitHub Appの発行などが挙げられています。一方でつまずいた点もあり、当初は「ドキュメントが必要かどうか」を判断する基準が緩く、69件中9件(約13%)がマージされずにクローズされたとのことです。そのため、CIの変更や内部ヘルパーなど「ドキュメント不要」の具体例をプロンプトに追加し、精度を改善したと説明されています。

　また、クロスリポジトリでのプルリクエスト作成にあたっては、対象リポジトリを2回チェックアウトする(現在の作業ディレクトリとして1回、_repos/aspire.dev 以下にもう1回)ことで、safe-outputsハンドラーが確実にリポジトリを見つけられるようにする工夫も行われています。差分が大きい場合にプロンプトの容量を圧迫する問題については、エージェントが動く前のbashステップでプルリクエストのメタデータ(リンクされたissue、マイルストーン、ベースブランチなど)を事前に抽出し、要約した情報だけをエージェントに渡す形で対処しているとのことです。