Implementation:Microsoft Autogen Docs Build Workflow

Knowledge Sources	Microsoft_Autogen
Domains	CI_CD, Documentation, GitHub_Pages
Last Updated	2026-02-11 17:00 GMT

Overview

A sophisticated GitHub Actions workflow that builds versioned documentation for multiple releases and deploys them to GitHub Pages.

Description

This workflow orchestrates the building and deployment of documentation for the AutoGen project. It builds documentation for 25+ different versions (including stable, dev, and historical releases from 0.2 to 0.7.5), generates redirect pages, creates JSON schemas for components, and handles both Python (Sphinx-based) and .NET (DocFX-based) documentation. The workflow includes a dedicated deploy job that publishes all artifacts to GitHub Pages, but only when running on the main branch.

Usage

This workflow is triggered by:

• Push events to the main branch
• Pull requests targeting main (builds but doesn't deploy)
• Manual workflow dispatch from the Actions tab

The workflow builds documentation across different historical versions to maintain a complete documentation archive with version switcher support.

Code Reference

Source Location

• Repository: Microsoft_Autogen
• File: .github/workflows/docs.yml

Signature

name: Docs
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true

jobs:
  build-04: # Python docs for v0.4+ (25+ version matrix)
  gen-redirects: # Generate redirect pages
  gen-component-schema: # Generate JSON schema
  build-02: # Legacy v0.2 docs with Docusaurus
  build-04-dotnet: # .NET API docs with DocFX
  deploy: # Deploy to GitHub Pages (main only)

Import

# Triggered by: Push to main, PR to main, or manual dispatch
# Uses: astral-sh/setup-uv@v5 for Python package management
# Uses: actions/setup-node@v4 for Node.js (v0.2 docs)
# Uses: actions/setup-dotnet@v4 for .NET documentation
# Uses: actions/deploy-pages@v4 for GitHub Pages deployment

I/O Contract

Inputs

Name	Type	Required	Description
github.ref	string	Yes	Branch reference (must be 'refs/heads/main' for deploy)
matrix.version.ref	string	Yes	Git reference for each documentation version
matrix.version.dest-dir	string	Yes	Target directory for built docs (e.g., 'stable', '0.7.5')
matrix.version.uv-version	string	Yes	UV package manager version to use
matrix.version.sphinx-release-override	string	No	Override for Sphinx release metadata
matrix.version.poe-dir	string	Yes	Directory for poethepoet task runner

Outputs

Name	Type	Description
GitHub Pages Site	URL	Deployed documentation site at github.io
Documentation Artifacts	Files	HTML documentation for all versions
Component Schema	JSON	JSON schema for component validation
Redirect Pages	HTML	Auto-generated redirect pages for URL management

Usage Examples

Automatic Build on Push

# Push to main branch triggers full build and deploy:
git push origin main
# Builds 25+ versions, generates schemas, and deploys to GitHub Pages

Preview Build on Pull Request

# Pull request builds docs but doesn't deploy:
gh pr create --base main --head feature-branch
# All docs are built and can be previewed via artifacts

Manual Workflow Dispatch

# Manually trigger documentation rebuild:
gh workflow run docs.yml --ref main

# View workflow status:
gh run list --workflow=docs.yml

# Download built documentation artifacts:
gh run download <run-id>

Viewing Specific Version Documentation

# Documentation URLs follow this pattern:
https://microsoft.github.io/autogen/dev/      # Development version
https://microsoft.github.io/autogen/stable/   # Stable release
https://microsoft.github.io/autogen/0.7.5/    # Specific version
https://microsoft.github.io/autogen/0.2/      # Legacy version
https://microsoft.github.io/autogen/dotnet/dev/ # .NET API docs

Job Details

build-04 Job

Matrix job that builds Python documentation for 25+ versions. Each matrix entry specifies:

• Git reference to checkout
• Destination directory
• UV version for dependency management
• Optional Sphinx release override
• Poethepoet directory location

Uses Sphinx for documentation generation and uploads artifacts for each version.

gen-redirects Job

Generates HTML redirect pages using a Python script. This ensures old URLs continue to work when documentation structure changes.

gen-component-schema Job

Runs gen-component-schema command to produce JSON schema definitions for component validation. Schema is placed in the schemas/ directory.

build-02 Job

Builds legacy v0.2 documentation using:

• Docusaurus for the website
• pydoc-markdown for API documentation
• Quarto for notebook rendering
• Node.js and npm/yarn for build process

build-04-dotnet Job

Builds .NET API documentation using DocFX. Includes a Python post-processing step that inserts Microsoft Clarity analytics tracking into all HTML files.

deploy Job

Conditional job that only runs on the main branch after all build jobs succeed. Downloads all artifacts, merges them into a single deploy directory, and publishes to GitHub Pages using the dedicated deployment action.

Version Matrix

The workflow builds documentation for these versions:

• dev - Latest development version from current branch
• stable - Current stable release (python-v0.7.5)
• 0.2.x - Legacy Docusaurus-based docs
• 0.4.0 - 0.4.9 - Historical releases
• 0.5.1 - 0.5.7 - Mid-version releases
• 0.6.1, 0.6.2, 0.6.4 - Recent releases
• 0.7.1 - 0.7.5 - Latest releases
• dotnet/dev - .NET API documentation

Each version may use different build tools and configurations based on the project structure at that point in time.

Related Pages

• Microsoft_Autogen_CI_Checks_Workflow - Code quality checks workflow
• Microsoft_Autogen_Dotnet_Build_Workflow - .NET build workflow
• Documentation_Versioning - Documentation version management
• GitHub_Pages_Deployment - Static site deployment
• Sphinx - Python documentation generator
• DocFX - .NET documentation generator