Documentation Deployment
The documentation workflow (documentation.yaml
) handles building and deploying project documentation using dual trigger mechanisms to ensure reliable deployment after releases. This system solves critical GitHub Actions limitations for automated documentation updates during releases.
Overview
The documentation deployment system features:
- Dual Trigger Architecture: Handles both direct documentation changes and release-triggered updates
- Workflow Run Pattern: Solves GitHub Actions
GITHUB_TOKEN
commit limitation - Intelligent Guard Jobs: Conditional deployment based on actual documentation changes
- Artifact-Based Communication: Reliable cross-workflow communication via artifacts
- GitHub Pages Integration: Automated deployment to GitHub Pages with Docusaurus
Advanced Trigger Architecture
The documentation workflow uses a sophisticated dual-trigger system to solve the GitHub Actions limitation where GITHUB_TOKEN
commits don't trigger other workflows:
1. Direct Push Trigger (Traditional)
on:
push:
branches: ["master"]
paths:
- "docs/**"
- "*.md"
- "README*.md"
- ".github/workflows/documentation.yaml"
- ".github/workflows/release.yml"
- ".github/workflows/release-*.yml"
- ".github/workflows/rw_*.yaml"
- ".github/tag_and_release/**"
Purpose: Handles direct documentation changes pushed to master branch
Triggers On:
- Documentation file changes
- Workflow file changes that affect release processes
- Configuration changes that impact documentation
2. Workflow Run Trigger (Release Integration)
on:
workflow_run:
workflows: ["release"]
types: [completed]
branches: ["master"]
Purpose: Automatically triggers after release workflow completion to handle documentation updates made during version bumps
Workflow Run Pattern Implementation
Problem Solved
GitHub Actions Limitation: GitHub Actions doesn't trigger workflows on commits made by GITHUB_TOKEN
(used in release workflows) to prevent infinite loops. This caused documentation workflow to never trigger after release workflow commits that updated documentation files.
Impact: Documentation would become stale after releases because version references in docs weren't being deployed.
Solution Architecture
Guard Job Implementation
The documentation workflow includes an intelligent guard job that provides conditional deployment logic:
Guard Job Logic
check_docs_changes:
if: github.event_name == 'workflow_run'
runs-on: ubuntu-latest
outputs:
should_deploy: ${{ steps.check_flag.outputs.should_deploy }}
steps:
- name: Download docs update flag from release workflow
uses: actions/download-artifact@v4
with:
name: release-docs-flag
run-id: ${{ github.event.workflow_run.id }}
- name: Check release workflow success and docs update flag
id: check_flag
run: |
# Verify release workflow succeeded
if [[ "${{ github.event.workflow_run.conclusion }}" != "success" ]]; then
echo "Release workflow did not succeed. Skipping documentation deployment."
echo "should_deploy=false" >> $GITHUB_OUTPUT
exit 0
fi
# Read docs update flag from artifact
DOCS_UPDATED=$(cat docs_updated.txt)
echo "Documentation update flag: $DOCS_UPDATED"
if [[ "$DOCS_UPDATED" == "true" ]]; then
echo "Documentation was updated during release. Proceeding with deployment."
echo "should_deploy=true" >> $GITHUB_OUTPUT
else
echo "No documentation updates detected. Skipping deployment."
echo "should_deploy=false" >> $GITHUB_OUTPUT
fi
Guard Job Functions
- Downloads Release Artifacts: Retrieves the
DOCS_UPDATED
flag from the completed release workflow - Verifies Release Success: Ensures the release workflow completed successfully
- Evaluates Update Flag: Checks if documentation files were actually updated during the release
- Controls Deployment: Only proceeds with documentation deployment if docs were updated
Conditional Deployment Logic
The main deployment job runs conditionally based on the trigger type:
deploy_documentation:
# Run for direct push OR workflow_run with docs changes
if: |
github.event_name == 'push' ||
(github.event_name == 'workflow_run' && needs.check_docs_changes.outputs.should_deploy == 'true')
needs: [check_docs_changes]
runs-on: ubuntu-latest
Deployment Conditions:
- Direct Push Events: Always deploy (traditional behavior)
- Workflow Run Events: Only deploy if guard job approves (
should_deploy=true
)
Release Workflow Integration
The release workflow (release.yml
) has been enhanced to support this pattern through the DOCS_UPDATED
flag system.
DOCS_UPDATED Flag Generation
During the version bump process, the release workflow:
1. Tracks Documentation Updates
Uses existing DOCS_UPDATED
flag from bump step logic that already determines if documentation files need updating:
# Version bump logic already sets DOCS_UPDATED flag
DOCS_UPDATED=false
# Check if documentation files that reference versions need updating
if [[ -f "docs/contents/development/ci-cd/index.mdx" ]] ||
[[ -f "docs/contents/document/installation.md" ]] ||
[[ -f "docs/contents/document/README.md" ]]; then
DOCS_UPDATED=true
fi
2. Updates Version References
Automatically updates documentation files that reference the package version:
docs/contents/development/ci-cd/index.mdx
docs/contents/document/installation.md
docs/contents/document/README.md
3. Sets Output Flag
Outputs the DOCS_UPDATED
flag for downstream workflows:
# Output DOCS_UPDATED flag for documentation workflow trigger
echo "docs_updated=$DOCS_UPDATED" >> $GITHUB_OUTPUT
4. Emits Artifact
Uploads the flag as an artifact for the documentation workflow:
- name: Upload docs update flag for downstream documentation workflow
uses: actions/upload-artifact@v4
with:
name: release-docs-flag
path: docs_updated.txt
retention-days: 1
Documentation Deployment Process
Environment Setup
The documentation deployment uses modern Node.js tooling:
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '22'
- name: Setup pnpm
uses: pnpm/action-setup@v4
with:
version: 8
run_install: false
- name: Get pnpm store directory
shell: bash
run: echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
- name: Setup pnpm cache
uses: actions/cache@v4
with:
path: ${{ env.STORE_PATH }}
key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
restore-keys: |
${{ runner.os }}-pnpm-store-
Build Process
Docusaurus Build Steps:
-
Install Dependencies:
pnpm install --frozen-lockfile
-
Build Static Documentation:
pnpm build
-
Generate Optimized Assets:
- Static HTML, CSS, and JavaScript
- Optimized images and assets
- Search index generation
- PWA manifests
GitHub Pages Deployment
Deployment Steps:
-
Configure GitHub Pages Environment:
- name: Setup Pages
uses: actions/configure-pages@v5 -
Upload Built Documentation:
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: ./build -
Deploy to GitHub Pages:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
Key Benefits
✅ Reliable Triggering: Documentation deploys automatically after releases that update docs
✅ No Infinite Loops: Guard job prevents unnecessary deployments
✅ Efficient: Only deploys when documentation actually changes
✅ Backward Compatible: Direct push functionality remains unchanged
✅ Intelligent: Uses existing business logic to determine if docs need updating
✅ Fast: Leverages pnpm caching for quick builds
✅ Robust: Multiple fallback mechanisms and error handling
Advanced Features
Multi-Path Trigger Monitoring
The workflow monitors multiple file paths to ensure comprehensive documentation updates:
paths:
- "docs/**" # Core documentation
- "*.md" # Root markdown files
- "README*.md" # README variants
- ".github/workflows/documentation.yaml" # This workflow
- ".github/workflows/release.yml" # Release workflow
- ".github/workflows/release-*.yml" # Release variants
- ".github/workflows/rw_*.yaml" # Reusable workflows
- ".github/tag_and_release/**" # Release configuration
Intelligent Artifact Management
Artifact Lifecycle:
- Creation: Release workflow creates
release-docs-flag
artifact - Consumption: Documentation workflow downloads and reads flag
- Cleanup: Artifacts automatically expire after 1 day
- Error Handling: Missing artifacts result in graceful skipping
Cross-Workflow Communication
Communication Pattern:
Troubleshooting
Common Issues and Solutions
Documentation Not Deploying After Release
Symptoms: Documentation doesn't update after a release that should have triggered it.
Diagnosis Steps:
- Check that the release workflow completed successfully
- Verify that documentation files were actually updated (check
DOCS_UPDATED
flag in release logs) - Review the guard job output in the documentation workflow
- Ensure the
release-docs-flag
artifact was created
Solutions:
# Check release workflow status
gh run list --workflow=release.yml --limit=1
# Check documentation workflow status
gh run list --workflow=documentation.yaml --limit=1
# View specific run logs
gh run view <run-id> --log
Guard Job Failing
Symptoms: Documentation workflow guard job fails with artifact download errors.
Common Causes:
- Release workflow didn't upload the
release-docs-flag
artifact - Artifact download permissions incorrect
- Workflow run ID not accessible
Solutions:
-
Check Artifact Upload:
# Verify this step exists in release workflow
- name: Upload docs update flag for downstream documentation workflow
uses: actions/upload-artifact@v4
with:
name: release-docs-flag
path: docs_updated.txt -
Verify Permissions:
permissions:
contents: read
actions: read # Required for artifact download -
Check Workflow Run ID:
# The workflow_run event should provide the correct run ID
echo "Release run ID: ${{ github.event.workflow_run.id }}"
Deployment Timing Issues
Expected Behavior:
- Workflow run triggers happen after the triggering workflow completes
- Documentation deployment occurs ~1-2 minutes after release completion
- Monitor both workflows to track the complete process
Debugging Timeline:
- Release workflow starts and completes
- Documentation workflow triggered via
workflow_run
- Guard job evaluates
DOCS_UPDATED
flag - Deployment job runs if flag is
true
Performance Optimization
Build Speed Improvements
pnpm Caching Strategy:
- name: Setup pnpm cache
uses: actions/cache@v4
with:
path: ${{ env.STORE_PATH }}
key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
restore-keys: |
${{ runner.os }}-pnpm-store-
Benefits:
- ~60% faster builds on cache hit
- Reduced bandwidth usage
- More reliable builds in case of registry issues
Conditional Processing
Skip Logic:
- Guard job prevents unnecessary builds
- Direct evaluation of
DOCS_UPDATED
flag - Early exit for workflow_run events with no doc changes
Best Practices
For Contributors
- Documentation Changes: Direct documentation changes trigger immediate deployment
- Release Integration: Version-related doc updates happen automatically during releases
- Testing: Use staging branches to test documentation changes before merging
- Monitoring: Check both release and documentation workflow statuses for complete picture
For Maintainers
- Artifact Management: Keep artifact retention short (1 day) to save storage
- Error Handling: Monitor guard job failures and artifact issues
- Performance: Review build times and optimize pnpm cache usage
- Security: Ensure proper permissions for cross-workflow artifact access
Configuration Management
Release Integration Checklist:
- ✅ Release workflow outputs
DOCS_UPDATED
flag - ✅ Release workflow uploads
release-docs-flag
artifact - ✅ Documentation workflow has
workflow_run
trigger - ✅ Guard job correctly evaluates flag
- ✅ Deployment job has proper conditional logic
🔗 Related Documentation:
- Release System - Learn about the release workflow that triggers documentation updates
- Continuous Integration - Understanding the broader CI/CD context
- Developer Guide - Advanced troubleshooting and configuration