# GitHub Actions CI/CD Setup Checklist

## ✅ mdBook Documentation Workflows

### Workflows Installed
- [x] `.github/workflows/mdbook-build-deploy.yml` — Build & deploy mdBook
- [x] `.github/workflows/docs-lint.yml` — Markdown & configuration validation
- [x] `.github/workflows/mdbook-publish.yml` — Custom deployment trigger

### Pre-Deployment Configuration

#### For GitHub Pages Deployment
- [ ] Go to Repository **Settings** → **Pages**
- [ ] Select **Source**: GitHub Actions
- [ ] Click **Save**
- [ ] (Optional) Add **Custom domain** (e.g., docs.vapora.io)
- [ ] (Optional) Enable **Enforce HTTPS**

#### For Custom Deployment
- [ ] Review `.github/workflows/mdbook-publish.yml`
- [ ] Add custom deployment script (S3, Docker, etc.)
- [ ] Add secrets in **Settings** → **Secrets and variables** → **Actions**
- [ ] Test with `git push origin main` to docs/

### Documentation Files Created
- [x] `docs/mdbook-setup.md` — mdBook setup guide
- [x] `docs/github-actions-setup.md` — Complete workflow documentation
- [x] `docs/deployment-guide.md` — Deployment procedures
- [x] `.github/WORKFLOWS.md` — Quick reference for developers

## 🚀 Initial Deployment Test

### Local Testing
```bash
# Build locally
cd docs && mdbook build

# Verify output
ls -la docs/book/index.html
du -sh docs/book/

# Serve locally
mdbook serve
# Open http://localhost:3000
```

### Trigger First Workflow
```bash
# Make a test commit to docs/
git add docs/README.md
git commit -m "test: trigger mdBook workflow"
git push origin main

# Monitor workflow
# Go to: Repository → Actions → mdBook Build & Deploy
```

### Verify Workflow Execution
- [ ] Workflow triggered automatically
- [ ] Build job completed successfully
- [ ] Quality check passed
- [ ] Artifact uploaded (check Artifacts section)
- [ ] (If Pages enabled) Deployment job completed
- [ ] Check GitHub Actions workflow summary

## 📊 Post-Deployment Verification

### GitHub Pages (if enabled)
- [ ] Go to **Settings** → **Pages**
- [ ] See message: "Your site is live at: https://..."
- [ ] Click link and verify site loads
- [ ] Test navigation
- [ ] Test search functionality
- [ ] Test dark mode toggle
- [ ] Verify on mobile device

### Artifact Management
- [ ] Artifacts appear in workflow runs
- [ ] Download an artifact and verify structure
- [ ] Verify 30-day retention policy
- [ ] Check total artifact size

### Workflow Monitoring
- [ ] Open workflow run details
- [ ] Verify all steps completed
- [ ] Check step summaries
- [ ] Review any warnings

## 🔐 Security Configuration

### Branch Protection
- [ ] Go to **Settings** → **Branches**
- [ ] Add rule for `main` branch
- [ ] Enable "Require pull request reviews"
- [ ] Enable "Require status checks to pass"
- [ ] Select: mdBook Build & Deploy
- [ ] Select: docs-lint

### Secrets Management
- [ ] If using custom deployment:
  - [ ] Go to **Settings** → **Secrets and variables** → **Actions**
  - [ ] Add deployment secrets (e.g., DEPLOY_TOKEN, AWS_KEY)
  - [ ] Verify secrets not logged in workflow runs
  - [ ] Set up secret rotation schedule

## 📚 Team Communication

### Documentation Updates Needed
- [ ] Update main README.md with docs link
- [ ] Update CONTRIBUTING.md with doc workflow
- [ ] Update release notes template with docs updates
- [ ] Add link to `.github/WORKFLOWS.md` in project wiki

### Team Notification
- [ ] Announce workflows to team
- [ ] Share `.github/WORKFLOWS.md` quick reference
- [ ] Point to `docs/deployment-guide.md` for deployment info
- [ ] Schedule documentation training if needed

## 🔄 Operational Procedures

### Weekly Checks
- [ ] Monitor workflow run times (should be ~1 min)
- [ ] Check for any failed runs
- [ ] Review artifact sizes
- [ ] Verify no broken links in quality checks

### Monthly Maintenance
- [ ] Update workflow dependencies (if any)
- [ ] Review and rotate secrets if used
- [ ] Archive old artifacts (GitHub does auto-cleanup)
- [ ] Update documentation as needed

### Before Major Release
- [ ] Build and test documentation locally
- [ ] Push to main to trigger full workflow
- [ ] Verify all checks pass
- [ ] Download and review artifact
- [ ] Verify GitHub Pages site (if enabled)
- [ ] Announce docs update to users

## 📞 Troubleshooting Reference

### Workflow Fails
1. Go to **Actions** → Failed workflow run
2. Click job name to see logs
3. Expand failed step for error details
4. Compare with `.github/WORKFLOWS.md` troubleshooting
5. Fix issue and push again

### Links Broken
1. Check `docs/src/SUMMARY.md` paths
2. Verify files exist in referenced locations
3. Use relative paths only: `../section/file.md`
4. Rebuild locally to test

### GitHub Pages Not Updating
1. Wait 1-2 minutes
2. Hard refresh (Ctrl+Shift+R)
3. Check **Settings** → **Pages** → Source
4. Verify workflow completed successfully
5. Check Pages deployment job logs

## 📋 Final Verification

### All Checks Passing
- [ ] Workflow files created
- [ ] Documentation files created
- [ ] mdBook builds successfully locally
- [ ] First workflow run successful
- [ ] All quality checks pass
- [ ] Artifacts generate correctly
- [ ] GitHub Pages shows docs (if enabled)
- [ ] Team notified

### System Ready
- [ ] Documentation workflow automated
- [ ] Developers can push docs changes
- [ ] Changes automatically deployed
- [ ] Quality validated
- [ ] No manual deployment steps needed

## 📈 Success Metrics

Track these metrics going forward:

| Metric | Target | Current |
|--------|--------|---------|
| Workflow run time | < 2 min | — |
| Build success rate | 100% | — |
| Artifact upload rate | 100% | — |
| Lint warning rate | < 5% | — |
| Pages uptime | 99.9% | — |

---

## 🎯 Next Steps

1. **Complete pre-deployment checklist** above
2. **Configure GitHub Pages** (if desired)
3. **Push test commit** to trigger workflows
4. **Monitor first run** in Actions tab
5. **Verify deployment** (locally or on Pages)
6. **Notify team** of new workflow
7. **Document findings** in project wiki
8. **Schedule review** in 1 week to confirm stability

---

**Checklist Created**: 2026-01-12
**Status**: Ready to Deploy
**Support**: See `.github/WORKFLOWS.md` for quick reference