AI Streamlines DevSecOps Documentation

The perennial problem of outdated documentation lagging behind product releases is seeing a significant shift, thanks to AI. GitHub's new Agentic Workflows are now streamlining this critical aspect of development, particularly for teams grappling with cross-repository documentation.

According to the GitHub Blog, the Aspire team, a small unit building dev tools for distributed applications, has harnessed these workflows to automate documentation generation. This innovative approach addresses a common bottleneck in AI-powered DevSecOps: ensuring that documentation for new features is not only created promptly but also accurately reflects the underlying code changes.

Automating the Documentation Lag

Before Agentic Workflows, Aspire faced a familiar scenario: a writer would attempt to reverse-engineer changes from a closed pull request, weeks after the engineer had moved to a new project. This 'reverse-engineering tax' resulted in documentation often shipping after the feature had already been released, sometimes multiple times.

The Aspire team's solution leveraged GitHub Agentic Workflows to bridge the gap between their product repository (microsoft/aspire) and their documentation site (microsoft/aspire.dev). This cross-repository challenge is often where traditional automation falters due to security concerns around broad access tokens.

Agentic Workflows: The Technical Core

GitHub Agentic Workflows, a project from the GitHub Next team, functions like GitHub Actions but with an AI model as the work-item processor. A workflow is defined in a markdown file with an English-language prompt, which then compiles into a standard GitHub Actions workflow (.lock.yml).

Crucially, the agent operates with a constrained toolset and read-only access to GitHub. Any write operations, such as creating pull requests or issues, are not performed directly by the agent. Instead, the agent emits an 'intent' as a JSON blob, which a separate, narrowly scoped 'safe-outputs handler' then materializes against a per-workflow GitHub app.

This architecture is a security game-changer. It allows for automated content generation while ensuring that all write actions pass through a verifiable pipeline with explicit allow-lists, satisfying stringent security reviews.

The End-to-End Pipeline

The Aspire team's workflow, 'pr-docs-check.md', initiates when a pull request is merged into the 'main' or 'release/*' branch. It first deterministically resolves the target documentation branch, often mapping product repository milestones to specific release branches in the docs repository.

The agent then analyzes the code diff and linked issues to determine if documentation is required. If so, it drafts the content in a checked-out 'microsoft/aspire.dev' workspace, adhering to established doc-writer guidelines, including voice, MDX conventions, and Starlight components.

Upon completion, the agent emits a 'create_pull_request' safe-output. The safe-outputs handler takes over, creating a draft pull request in the documentation repository, automatically assigning the original feature's reviewer (the Subject Matter Expert, or SME) to approve the documentation. This ensures that the engineer who shipped the feature also validates its accompanying documentation.

Within minutes of merging a product change, the engineer receives a notification with a link to the draft documentation. This rapid feedback loop and integrated review process drastically reduce the documentation lag, moving security and accuracy further left in the development lifecycle.