Automating cross-repo documentation with GitHub Agentic Workflows
The Aspire team used GitHub Agentic Workflows to automate documentation across its product and documentation repositories. For versions 13.3 and 13.4, the system produced 82 documentation pull requests, typically within 44.8 hours of the corresponding product change, with review from the engineer who shipped the feature. The approach combines AI-generated drafts with deterministic branch selection and tightly controlled write permissions. ## The Cross-Repository Documentation Problem - Product code lives in `microsoft/aspire`, while documentation lives in `microsoft/aspire.dev`. - The old process depended on writers discovering changes weeks later and reconstructing intent from closed pull requests. - Engineers often had limited context by the time clarification was requested. - Broad repository tokens were unacceptable, making secure cross-repository automation difficult. ## How GitHub Agentic Workflows Work - Workflows are authored as Markdown files with YAML-style frontmatter and natural-language instructions. - A compiler generates a standard GitHub Actions `.lock.yml` workflow. - An agent analyzes repository data and produces proposed actions as JSON rather than writing directly to GitHub. - A separate “safe-outputs” handler executes only explicitly permitted actions through a narrowly scoped GitHub App. - This separation provides AI flexibility while preserving security controls and auditability. ## The Automated Documentation Pipeline - The `pr-docs-check.md` workflow runs when a pull request is merged into `main` or a `release/*` branch. - A deterministic Bash script resolves the documentation target branch before the agent runs: - Product pull request milestone, such as `13.4`, maps to `release/13.4`. - Linked issue milestones are checked next. - The pull request’s base branch is used if it matches a release pattern. - Otherwise, documentation targets `main`. - The agent: - Reviews the product diff and linked issues. - Determines whether documentation is necessary. - Checks out `microsoft/aspire.dev`. - Writes documentation using the project’s existing writing conventions and Starlight/MDX components. - The workflow creates a draft documentation pull request with: - A `[docs]` title prefix. - The `docs-from-code` label. - A restricted base branch. - The documentation repository as the target. - The subject-matter expert who reviewed the original product pull request as reviewer. - A comment containing the documentation pull request link is posted back to the source pull request, while older workflow comments are minimized on reruns. ## Security Through Safe Outputs - The agent receives constrained GitHub tools and read access. - Repository access is limited through allowed repositories and a dedicated GitHub App. - Actions must use pinned, integrity-checked components through `min-integrity: approved`. - Write operations are restricted to declared safe outputs, such as creating pull requests. - Documentation changes remain drafts and are never auto-merged. ## Results and Broader Fit - The process eliminated the need for additional staff or major process training. - Documentation drafts arrive shortly after the related code is merged, while the implementation context is still fresh. - The workflow preserves human review by routing drafts to the engineer or SME who approved the feature. - Both the automation documentation and `aspire.dev` use Astro and Starlight, making the tooling and publishing environment closely aligned. The practical recommendation is to use agentic automation for drafting and routing documentation, but keep branch resolution, permissions, and final review deterministic and human-controlled. This provides much of the speed of autonomous workflows without granting an AI agent unrestricted repository write access.
Read original(opens in new tab)
