Vapora/.github/ci_cd_checklist.md

GitHub Actions CI/CD Setup Checklist

✅ mdBook Documentation Workflows

Workflows Installed

• .github/workflows/mdbook-build-deploy.yml — Build & deploy mdBook
• .github/workflows/docs-lint.yml — Markdown & configuration validation
• .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

• docs/mdbook-setup.md — mdBook setup guide
• docs/github-actions-setup.md — Complete workflow documentation
• docs/deployment-guide.md — Deployment procedures
• .github/WORKFLOWS.md — Quick reference for developers

🚀 Initial Deployment Test

Local Testing

# 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

# 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