Automating Cross-Repo Documentation with GitHub Agentic Workflows
Streamline documentation processes with AI-powered GitHub Agentic Workflows.
1The Documentation Problem
Documentation updates are often time-consuming and error-prone for product teams. Writers typically notice changes weeks after engineers complete features, forcing them to reverse-engineer updates.
2Aspire Team's Solution
The Aspire team discovered GitHub Agentic Workflows to automate documentation processes. This tool enables cross-repo automation with AI-powered workflows, significantly speeding up documentation.
3GitHub Agentic Workflows
GitHub Agentic Workflows is a tool similar to GitHub Actions but powered by an AI model and equipped with security safeguards. Workflows are defined in markdown files and automatically converted into GitHub Actions workflows.
4Cross-Repo Automation
The Aspire team automated processes between the code repository and the documentation repository, speeding up documentation. This was achieved securely using narrowly scoped permissions instead of broad tokens.
5Automated Documentation Process
When a feature is completed, GitHub Agentic Workflows automatically generates a documentation draft. This draft is reviewed by the relevant engineer and integrated into the documentation repository.
6Security Measures
GitHub Agentic Workflows prevents the AI agent from writing directly to GitHub. Instead, the agent generates a JSON blob, which is processed by a narrowly scoped workflow.
7Milestone and Branch Management
The Aspire team maps milestones in the product repository to release branches in the documentation repository, ensuring documentation is created in the correct branch.
8Documentation Draft Creation
The AI agent analyzes code changes to generate a documentation draft. This draft is prepared in accordance with existing documentation standards.
9Safe Output Processing
The generated documentation draft is integrated into the documentation repository through a secure workflow. This process prevents automatic merging and ensures review by the relevant engineer.
10Notification and Tracking
When a documentation draft is created, a notification is sent to the relevant engineer. This ensures documentation is updated promptly and accurately.
11Results and Impact
With GitHub Agentic Workflows, the Aspire team significantly sped up documentation processes and reduced errors. This approach could serve as a solution for similar challenges faced by other teams.