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`:

```yaml
- 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**:
```yaml
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

```bash
# 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

```bash
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`:

```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`:

```yaml
- 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`:

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

### Add Custom Deployment

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

```yaml
- 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

```bash
# 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