This directory contains all GitHub Actions workflows, configurations, and documentation for the AI Meal Planner project's CI/CD infrastructure.
- Read the Quick Reference - WORKFLOWS_QUICK_REFERENCE.md
- Set up secrets - Follow SECRETS_SETUP.md
- Configure branch protection - See WORKFLOWS.md
-
Run tests locally before pushing:
# Backend cd backend && pytest tests/unit/ -v --cov=app # Frontend cd frontend && npm test -- --coverage && npm run lint && npx tsc --noEmit
-
Push to your branch - Workflows auto-trigger
-
Check Actions tab - Monitor workflow status
-
Fix any failures - Review logs and artifacts
| Document | Purpose | When to Read |
|---|---|---|
| WORKFLOWS_QUICK_REFERENCE.md | Quick commands and troubleshooting | Daily use, quick lookups |
| WORKFLOWS.md | Comprehensive workflow documentation | Setup, deep dive, troubleshooting |
| SECRETS_SETUP.md | Step-by-step secrets configuration | Initial setup, adding new secrets |
| CI_CD_IMPLEMENTATION_SUMMARY.md | Implementation details and decisions | Understanding the system, onboarding |
| README.md | This file - directory overview | First time here |
| Workflow | File | Status Check | Coverage | Docs |
|---|---|---|---|---|
| Backend Unit Tests | backend-unit-tests.yml | test (3.11), test (3.12) |
80% | 📖 |
| Frontend Unit Tests | frontend-unit-tests.yml | test (20.x), test (22.x) |
75% | 📖 |
| Frontend Linting | frontend-lint.yml | lint |
N/A | 📖 |
| Playwright E2E Tests | playwright.yml | test |
N/A | 📖 |
All workflows are required status checks for merging to claude/main.
Push to claude/main → All workflows run (with path filters)
Pull Request → All workflows run (with path filters)
Manual Dispatch → Click "Run workflow" in Actions tab
.codecov.yml- Codecov coverage reporting configuration (root directory)- Path filters in each workflow (e.g.,
paths: ['backend/**'])
validate-workflows.sh- Validate workflow YAML syntax and best practicescd .github && ./validate-workflows.sh
| Secret | Purpose | Setup Guide |
|---|---|---|
CODECOV_TOKEN |
Upload coverage reports | SECRETS_SETUP.md |
SENTRY_DSN- Error trackingDATABASE_URL_TEST- Integration testsREDIS_URL_TEST- Integration tests
See SECRETS_SETUP.md for complete setup instructions.
# List all workflows
gh workflow list
# View recent runs
gh run list
# View specific workflow
gh run list --workflow=backend-unit-tests.yml# Via GitHub CLI
gh workflow run backend-unit-tests.yml --ref your-branch
gh workflow run frontend-unit-tests.yml --ref your-branch
gh workflow run frontend-lint.yml --ref your-branchOr use the Actions tab → Select workflow → Run workflow button
- Go to Actions tab
- Click on failed workflow run
- Expand failed step
- Download artifacts (if available)
- Run tests locally to reproduce
See WORKFLOWS.md for detailed troubleshooting.
- Edit
.github/workflows/{workflow-name}.yml - Validate syntax:
python3 -c "import yaml; yaml.safe_load(open('.github/workflows/{workflow-name}.yml'))" - Commit and push
- Monitor first run in Actions tab
- Run tests locally before pushing
- Keep coverage above thresholds (80% backend, 75% frontend)
- Fix lint errors immediately
- Review workflow logs when failures occur
- Update dependencies regularly
- Monitor CI minutes usage
- Skip tests with
[skip ci](unless absolutely necessary) - Ignore failing status checks
- Commit broken code hoping CI will catch it
- Leave failing tests for later
- Hardcode secrets in workflow files
- Disable required status checks
| Issue | Solution |
|---|---|
| Coverage below threshold | Add tests, check with --cov-report=term-missing |
| Linting failures | Run npm run lint -- --fix locally |
| Workflow not triggering | Check path filters match your changes |
| Codecov upload fails | Verify CODECOV_TOKEN is set |
| Timeout | Increase timeout in workflow YAML |
See WORKFLOWS.md for comprehensive troubleshooting guide.
| Workflow | Duration (cached) |
|---|---|
| Backend Unit Tests | ~1.5 min per version |
| Frontend Unit Tests | ~2 min per version |
| Frontend Linting | ~1 min |
| Playwright E2E | ~8-10 min |
Total per PR: ~15-20 minutes (parallel execution)
- Use caching - Already enabled for pip and npm
- Path filters - Already configured, workflows only run when relevant files change
- Matrix strategy - Already parallelized for multiple Python/Node versions
- Skip CI when needed - Use
[skip ci]in commit message for docs-only changes
GitHub provides free CI minutes for public repositories.
Free tier: 2,000 minutes/month Estimated usage: ~28 minutes per PR Capacity: ~70 PRs per month
Monitor usage at: Settings → Billing → Actions
- Review workflow logs for warnings
- Check for workflow failures
- Update dependencies in workflows (actions/setup-node, etc.)
- Review CI minutes usage
- Check Codecov dashboard for coverage trends
- Review and update coverage thresholds
- Update Node.js/Python versions in matrix
- Review and update documentation
Planned additions:
- Backend linting workflow (Black, isort, mypy, flake8)
- Backend integration tests (with database/Redis)
- Security scanning (Snyk, CodeQL, Trivy)
- Deployment workflows (staging, production)
- Performance testing (Lighthouse CI, load tests)
- Multi-browser E2E tests (Firefox, Safari)
See WORKFLOWS.md for details.
- Check documentation - Start with WORKFLOWS_QUICK_REFERENCE.md
- Review logs - Actions tab → Failed workflow → Expand steps
- Search issues - Check for similar problems
- Ask for help - Open issue with workflow run URL
Last Updated: 2025-12-05 Version: 1.0.0 Maintained By: Development Team
For questions or issues, please open a GitHub issue or consult the documentation above.