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/

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