Vapora/docs/github-actions-setup.md

GitHub Actions Setup for mdBook Documentation

Overview

Three automated workflows have been configured to manage mdBook documentation:

1. mdBook Build & Deploy — Builds documentation and validates quality
2. mdBook Publish & Sync — Handles downstream deployment notifications
3. Documentation Lint & Validation — Validates markdown and configuration

📋 Workflows

1. mdBook Build & Deploy

File: .github/workflows/mdbook-build-deploy.yml

Triggers:

• Push to main branch when docs/** or workflow file changes
• Pull requests to main when docs/** changes

Jobs:

Build Job

• ✅ Installs mdBook (cargo install mdbook)
• ✅ Builds documentation (mdbook build)
• ✅ Validates HTML output (checks for essential files)
• ✅ Counts generated pages
• ✅ Uploads artifact (retained 30 days)
• ✅ Provides build summary

Outputs:

docs/book/
├── index.html
├── print.html
├── css/
├── js/
├── fonts/
└── ... (all mdBook assets)

Artifact: mdbook-site-{commit-sha}

Quality Check Job

• ✅ Verifies content (VAPORA in index.html)
• ✅ Checks for empty files
• ✅ Validates CSS files
• ✅ Generates file statistics
• ✅ Reports total size and file counts

GitHub Pages Deployment Job

• ✅ Runs on push to main only (skips PRs)
• ✅ Sets up GitHub Pages environment
• ✅ Uploads artifact to Pages
• ✅ Deploys to GitHub Pages (if configured)
• ✅ Continues on error (handles non-GitHub deployments)

Key Features:

• Concurrent runs on same ref are cancelled
• Artifact retained for 30 days
• Supports GitHub Pages or custom deployments
• Detailed step summaries in workflow run

2. mdBook Publish & Sync

File: .github/workflows/mdbook-publish.yml

Triggers:

• Runs after mdBook Build & Deploy workflow completes successfully
• Only on main branch

Jobs:

Download & Publish Job

• ✅ Finds mdBook build artifact
• ✅ Creates deployment record
• ✅ Provides deployment summary

Use Cases:

• Trigger custom deployment scripts
• Send notifications to deployment services
• Update documentation registry
• Sync to content CDN

3. Documentation Lint & Validation

File: .github/workflows/docs-lint.yml

Triggers:

• Push to main when docs/** changes
• All pull requests when docs/** changes

Jobs:

Markdown Lint Job

• ✅ Installs markdownlint-cli
• ✅ Validates markdown formatting
• ✅ Reports formatting issues
• ✅ Non-blocking (doesn't fail build)

Checked Rules:

• MD031: Blank lines around code blocks
• MD040: Code block language specification
• MD032: Blank lines around lists
• MD022: Blank lines around headings
• MD001: Heading hierarchy
• MD026: No trailing punctuation
• MD024: No duplicate headings

mdBook Config Validation Job

• ✅ Verifies book.toml exists
• ✅ Verifies src/SUMMARY.md exists
• ✅ Validates TOML syntax
• ✅ Checks directory structure
• ✅ Tests build syntax

Content Validation Job

• ✅ Validates directory structure
• ✅ Checks for README.md in subdirectories
• ✅ Detects absolute links (should be relative)
• ✅ Validates SUMMARY.md links
• ✅ Reports broken references

Status Checks:

• ✅ README.md present in each subdirectory
• ✅ All links are relative paths
• ✅ SUMMARY.md references valid files

---

🔧 Configuration

Enable GitHub Pages Deployment

For GitHub.com repositories:

1. Go to repository Settings → Pages
2. Select:
   • Source: GitHub Actions
   • Branch: main
3. Optional: Add custom domain

Workflow will then:

• Auto-deploy to GitHub Pages on every push to main
• Available at: https://username.github.io/repo-name
• Or custom domain if configured

Custom Deployment (Non-GitHub)

For repositories on custom servers:

1. GitHub Pages deployment will be skipped (non-blocking)
2. Artifact will be uploaded and retained 30 days
3. Download from workflow run → Artifacts section
4. Use mdbook-publish.yml to trigger custom deployment

To add custom deployment script:

Add to .github/workflows/mdbook-publish.yml:

- name: Deploy to custom server
  run: |
    # Add your deployment script here
    curl -X POST https://your-docs-server/deploy \
      -H "Authorization: Bearer ${{ secrets.DEPLOY_TOKEN }}" \
      -F "artifact=@docs/book.zip"

Access Control

Permissions configured:

permissions:
  contents: read        # Read repository contents
  pages: write          # Write to GitHub Pages
  id-token: write       # For OIDC token
  deployments: write    # Write deployment records

---

📊 Workflow Status & Artifacts

View Workflow Runs

# In GitHub web UI:
# Repository → Actions → mdBook Build & Deploy

Shows:

• Build status (✅ Success / ❌ Failed)
• Execution time
• Step details
• Artifact upload status
• Job summaries

Download Artifacts

1. Open workflow run
2. Scroll to bottom → Artifacts section
3. Click mdbook-site-{commit-sha} → Download
4. Extract and use

Artifact Contents:

mdbook-site-{sha}/
├── index.html           # Main documentation page
├── print.html           # Printable version
├── css/
│   ├── general.css
│   ├── variables.css
│   └── highlight.css
├── js/
│   ├── book.js
│   ├── clipboard.min.js
│   └── elasticlunr.min.js
├── fonts/
└── FontAwesome/

---

🚨 Troubleshooting

Build Fails: "mdBook not found"

Fix: mdBook is installed via cargo install

• Requires Rust toolchain
• First run takes ~60 seconds
• Subsequent runs cached

Build Fails: "SUMMARY.md not found"

Fix: Ensure docs/src/SUMMARY.md exists

ls -la docs/src/SUMMARY.md

Build Fails: "Broken link in SUMMARY.md"

Error message: Cannot find file '../section/file.md'

Fix:

1. Verify file exists
2. Check relative path spelling
3. Use ../ for parent directory

GitHub Pages shows 404

Issue: Site deployed but pages not accessible

Fix:

1. Go to Settings → Pages
2. Verify Source is set to GitHub Actions
3. Wait 1-2 minutes for deployment
4. Hard refresh browser (Ctrl+Shift+R)

Artifact Not Uploaded

Issue: Workflow completed but no artifact

Fix:

1. Check build job output for errors
2. Verify docs/book/ directory exists
3. Check artifact upload step logs

---

📈 Performance

Build Times

Component	Time
Checkout	~5s
Install mdBook	~30s
Build documentation	~2-3s
Quality checks	~5s
Upload artifact	~10s
Total	~1 minute

Artifact Size

Metric	Value
Uncompressed	7.4 MB
Total files	100+
HTML pages	4+
Retention	30 days

---

🔐 Security

Permissions Model

• ✅ Read-only repository access
• ✅ Write-only GitHub Pages
• ✅ Deployment record creation
• ✅ No secrets required (unless custom deployment)

Adding Secrets for Deployment

If using custom deployment:

1. Go to Settings → Secrets and variables → Actions
2. Add secret: DEPLOY_TOKEN or DEPLOY_URL
3. Reference in workflow: ${{ secrets.DEPLOY_TOKEN }}

Artifact Security

• ✅ Uploaded to GitHub infrastructure
• ✅ Retained for 30 days then deleted
• ✅ Only accessible via authenticated session
• ✅ No sensitive data included

---

📝 Customization

Modify Build Output Directory

Edit docs/book.toml:

[build]
build-dir = "book"  # Change to "dist" or other

Then update workflows to match.

Add Pre-Build Steps

Edit .github/workflows/mdbook-build-deploy.yml:

- name: Build mdBook
  working-directory: docs
  run: |
    # Add custom pre-build commands
    # Example: Generate API docs first

    mdbook build

Modify Validation Rules

Edit .github/workflows/docs-lint.yml:

- name: Lint markdown files
  run: |
    # Customize markdownlint config
    markdownlint --config .markdownlint.json 'docs/**/*.md'

Add Custom Deployment

Edit .github/workflows/mdbook-publish.yml:

- name: Deploy to S3
  run: |
    aws s3 sync docs/book s3://my-bucket/docs \
      --delete --region us-east-1
  env:
    AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
    AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

---

📚 Integration with Documentation Workflow

Local Development

# Build locally before pushing
cd docs
mdbook serve

# Verify at http://localhost:3000

# Make changes, auto-rebuild
# Then push to trigger CI/CD

PR Review Process

1. Create branch and edit docs/**
2. Push to PR
3. Workflows automatically run:
   • ✅ Markdown linting
   • ✅ mdBook build
   • ✅ Content validation
4. All checks must pass
5. Merge PR
6. Main branch workflows trigger:
   • ✅ Full build + quality checks
   • ✅ Deploy to GitHub Pages

Release Documentation

When releasing new version:

1. Update version references in docs
2. Commit to main
3. Workflows automatically:
   • ✅ Build documentation
   • ✅ Deploy to GitHub Pages
   • ✅ Create deployment record
4. New docs version immediately live

---

🔍 Monitoring

GitHub Actions Dashboard

View all workflows:

Repository → Actions

Workflow Run Details

Click any run to see:

• All job logs
• Step-by-step execution
• Artifact uploads
• Deployment status
• Step summaries

Email Notifications

Receive updates for:

• ✅ Workflow failures
• ✅ Required checks failed
• ✅ Deployment status changes

Enable in Settings → Notifications

---

📖 Quick Reference

Task	Command / Location
Build locally	cd docs && mdbook serve
View workflows	GitHub → Actions
Download artifact	Click workflow run → Artifacts
Check build status	GitHub commit/PR checks
Configure Pages	Settings → Pages → GitHub Actions
Add deployment secret	Settings → Secrets → Actions
Modify workflow	.github/workflows/mdbook-*.yml

---

✅ Verification Checklist

After setup, verify:

• .github/workflows/mdbook-build-deploy.yml exists
• .github/workflows/mdbook-publish.yml exists
• .github/workflows/docs-lint.yml exists
• docs/book.toml exists
• docs/src/SUMMARY.md exists
• First push to main triggers workflows
• Build job completes successfully
• Artifact uploaded (30-day retention)
• All validation checks pass
• GitHub Pages deployment (if configured)

---

Setup Date: 2026-01-12 Workflows Created: 3 Status: ✅ Ready for Production

For workflow logs, see: Repository → Actions → mdBook workflows