Vapora/.github/workflows.md

CI/CD Workflows Reference

Quick reference for all GitHub Actions workflows in this repository.

Documentation Workflows

1. mdBook Build & Deploy

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

When it runs:

• Push to main with changes in docs/
• Pull request to main with changes in docs/

What it does:

┌─────────────────┐
│  Build mdBook   │ (cargo install mdbook, mdbook build)
└────────┬────────┘
         │
         ├──→ ✅ Validate HTML output
         │
         ├──→ ✅ Quality checks (content, CSS, JS)
         │
         ├──→ ✅ Upload artifact (30-day retention)
         │
         └──→ ✅ Deploy to GitHub Pages (if configured)

Artifacts: mdbook-site-{commit-sha}

Access: Actions → mdBook Build & Deploy → View Run → Download

---

2. Documentation Lint & Validation

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

When it runs:

• Push to main with changes in docs/
• All pull requests with changes in docs/

What it does:

┌──────────────────────┐
│  Markdown Linting    │ (markdownlint)
└────────┬─────────────┘
         │
         ├──→ 📋 Check MD031, MD040, MD032, MD022, etc.
         │
         ├──→ ⚠️  Report issues (non-blocking)
         │
         └──→ ✅ Pass even if warnings found

Checks:

• ✅ Code block formatting (markdown compliance)
• ✅ mdBook configuration validity
• ✅ Directory structure (README.md in all dirs)
• ✅ Link validation (all links exist)
• ✅ No absolute paths (should be relative)

---

3. mdBook Publish & Sync

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

When it runs:

• After mdBook Build & Deploy completes successfully
• Only on main branch

What it does:

┌─────────────────────────┐
│  Triggered by Build Job │
└────────┬────────────────┘
         │
         ├──→ 📥 Download artifact
         │
         ├──→ 📝 Create deployment record
         │
         └──→ 🚀 Ready for custom deployment

Purpose: Enables custom deployment workflows

---

Code Workflows

Rust CI

File: .github/workflows/rust-ci.yml

Triggers: Push/PR on Rust changes

Jobs:

• 🔒 Security audit (cargo audit)
• ✅ Check + Format + Clippy
• 🧪 Tests (cargo test)

---

Nushell Lint

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

Triggers: Push/PR on **/*.nu changes

---

Nickel Typecheck

File: .github/workflows/nickel-typecheck.yml

Triggers: Push/PR on Nickel changes

---

📊 Workflow Dashboard

View all workflows:

Repository → Actions

See:

• ✅ Passing runs
• ❌ Failed runs
• ⏳ In progress
• Artifacts

---

🔑 Quick Actions

After Editing docs/

# Local preview
cd docs && mdbook serve

# Push to trigger CI/CD
git add docs/
git commit -m "docs: update content"
git push origin main

# Workflows trigger automatically
# → GitHub Actions → mdBook workflows

Download Built Documentation

1. Go to Actions → mdBook Build & Deploy
2. Click latest successful run
3. Scroll to Artifacts
4. Download mdbook-site-{sha}

View Workflow Details

1. Go to Actions
2. Select workflow name
3. Click run
4. Expand job to see:
   • 📝 Step logs
   • ⏱️ Execution times
   • 📊 Step summaries
   • 📦 Artifacts

---

🐛 Common Issues

Issue	Fix
Build fails: mdBook not found	First run installs mdBook (~30s)
Lint warnings on MD031	Add blank lines around code blocks
Links broken	Use relative paths: ../section/file.md
GitHub Pages 404	Wait 1-2 min, check Pages settings
PR checks fail	Fix issues shown in workflow logs

---

✅ Status Checks for PR

When you submit a PR, these checks must pass:

• ✅ mdBook Build & Deploy — Build succeeds
• ✅ Documentation Lint & Validation — Markdown valid
• ✅ Any other CI — Rust tests, etc.

All must be ✅ before merge.

---

📋 For Documentation Changes

Workflow:

1. Create branch: git checkout -b docs/my-change
2. Edit docs/**/*.md
3. Test locally: cd docs && mdbook serve
4. Push and open PR
5. Workflows run automatically
6. Address any feedback
7. Merge when all checks pass
8. Changes auto-deploy to GitHub Pages

---

🔄 Full CI/CD Pipeline

Push to main
    │
    ├─→ Rust CI (code checks)
    │
    ├─→ Nushell Lint
    │
    ├─→ Nickel Typecheck
    │
    ├─→ mdBook Build & Deploy
    │   ├─→ Build
    │   ├─→ Quality Check
    │   └─→ Deploy to Pages
    │
    ├─→ Documentation Lint & Validation
    │
    └─→ mdBook Publish & Sync

All pass → ✅ Build successful

---

For detailed configuration, see:

• docs/GITHUB_ACTIONS_SETUP.md
• .github/workflows/mdbook-build-deploy.yml
• .github/workflows/docs-lint.yml
• .github/workflows/mdbook-publish.yml