Automating Cross-Repository Documentation with Agentic Workflows
This article details GitHub Engineering's approach to automating documentation generation across separate code and documentation repositories using GitHub Agentic Workflows. It highlights the architectural considerations for secure cross-repo automation, emphasizing a constrained agent model and a safe-outputs handler, and discusses the system's impact on developer workflow and documentation quality.
Read original on GitHub EngineeringThe core problem addressed is the delay and friction in keeping documentation synchronized with rapidly evolving product code, especially when code and documentation reside in different GitHub repositories. This scenario presents significant security challenges for automation, as granting broad repository access to an automated agent is undesirable.
GitHub Agentic Workflows Architecture
GitHub Agentic Workflows leverage a model-as-processor approach for automation. A workflow is defined in Markdown with YAML frontmatter and an English prompt. This configuration is compiled into a standard GitHub Actions workflow. The key architectural decision for security and control is the separation of agent reasoning from direct write access to GitHub.
Key Security Principle: Separation of Concerns
The agent itself does not directly write to GitHub. Instead, it emits *intent* as a JSON blob. A separate, narrowly scoped safe-outputs handler then materializes this intent using a per-workflow GitHub App with tightly controlled permissions. This design ensures that the agent's potentially 'fuzzy' reasoning is always mediated by a 'boring, secure' pipeline with explicit allow-lists and constraints.
End-to-End Pipeline Flow
- Trigger: The `pr-docs-check.md` workflow in the product repo (`microsoft/aspire`) is triggered on `pull_request: closed` events for `main` or `release/*` branches, specifically when `merged == true`.
- Target Branch Resolution: Before agent execution, a deterministic bash script resolves the target documentation branch (e.g., `release/13.4` for product milestone 13.4). This ensures the agent works with precise, non-generated metadata.
- Agent Execution: The agent reads the pull request diff and linked issues. It decides if documentation is needed and, if so, drafts content in a checked-out docs repo workspace.
- Safe-Outputs Materialization: The agent emits a `create_pull_request` intent. The safe-outputs handler then creates a draft pull request in the docs repo (`microsoft/aspire.dev`) with a specific title prefix, label, and assigns the original feature's SME as the reviewer.
- User Notification: A companion job posts a comment on the original product pull request with a link to the newly created docs pull request, notifying the engineer to review.
Security Contract and Guardrails
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
fallback-as-issue: trueThe system's security relies on a tightly defined contract. Each workflow is associated with a dedicated GitHub App token, scoped to precisely two repositories (product and docs) and with minimal permissions. The `safe-outputs` configuration explicitly defines what actions the agent is permitted to request, such as creating draft pull requests with specific prefixes, labels, and target branches. Crucially, sensitive files like `AGENTS.md` and security configurations are explicitly blocked from agent modification, and a fallback mechanism ensures issues are created if pull request generation fails.