a395bd972f
Some checks failed
Rust CI / Security Audit (push) Has been cancelled
Rust CI / Check + Test + Lint (nightly) (push) Has been cancelled
Rust CI / Check + Test + Lint (stable) (push) Has been cancelled
mdBook Build & Deploy / Build mdBook (push) Has been cancelled
Nickel Type Check / Nickel Type Checking (push) Has been cancelled
mdBook Build & Deploy / Documentation Quality Check (push) Has been cancelled
mdBook Build & Deploy / Deploy to GitHub Pages (push) Has been cancelled
mdBook Build & Deploy / Notification (push) Has been cancelled
213 lines
6.1 KiB
Markdown
213 lines
6.1 KiB
Markdown
# 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
|