diff --git a/docs/guides/TESTING_GATED_WORKFLOWS.md b/docs/guides/TESTING_GATED_WORKFLOWS.md new file mode 100644 index 000000000..28bee4bcc --- /dev/null +++ b/docs/guides/TESTING_GATED_WORKFLOWS.md @@ -0,0 +1,329 @@ +# Testing Enterprise Gated Workflows with Act + +This guide shows how to test the Enterprise Gated CI/CD workflows locally using [act](https://github.com/nektos/act). + +## Prerequisites + +```bash +# Install act (if not already installed) +# macOS +brew install act + +# Linux +curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash + +# Windows +choco install act-cli +``` + +## Quick Start + +```bash +cd frontends/nextjs + +# List all workflow jobs +npm run act -- -l + +# List gated CI jobs specifically +npm run act -- -W ../.github/workflows/gated-ci.yml -l + +# List gated deployment jobs +npm run act -- -W ../.github/workflows/gated-deployment.yml -l +``` + +## Testing Individual Gates + +### Gate 1: Code Quality + +```bash +# Test entire Gate 1 +npm run act -- -j gate-1-start -W ../.github/workflows/gated-ci.yml +npm run act -- -j prisma-check -W ../.github/workflows/gated-ci.yml +npm run act -- -j typecheck -W ../.github/workflows/gated-ci.yml +npm run act -- -j lint -W ../.github/workflows/gated-ci.yml +npm run act -- -j security-scan -W ../.github/workflows/gated-ci.yml +npm run act -- -j gate-1-complete -W ../.github/workflows/gated-ci.yml +``` + +### Gate 2: Testing + +```bash +# Test entire Gate 2 +npm run act -- -j gate-2-start -W ../.github/workflows/gated-ci.yml +npm run act -- -j test-unit -W ../.github/workflows/gated-ci.yml +npm run act -- -j test-e2e -W ../.github/workflows/gated-ci.yml +npm run act -- -j test-dbal-daemon -W ../.github/workflows/gated-ci.yml +npm run act -- -j gate-2-complete -W ../.github/workflows/gated-ci.yml +``` + +### Gate 3: Build & Package + +```bash +# Test entire Gate 3 +npm run act -- -j gate-3-start -W ../.github/workflows/gated-ci.yml +npm run act -- -j build -W ../.github/workflows/gated-ci.yml +npm run act -- -j quality-check -W ../.github/workflows/gated-ci.yml +npm run act -- -j gate-3-complete -W ../.github/workflows/gated-ci.yml +``` + +### Gate 4: Review & Approval + +```bash +# Test Gate 4 (PR only) +npm run act -- -j gate-4-review-required -W ../.github/workflows/gated-ci.yml -e pr-event.json +npm run act -- -j gate-4-complete -W ../.github/workflows/gated-ci.yml -e pr-event.json +``` + +### Gate 5: Deployment + +```bash +# Test staging deployment +npm run act -- -j deploy-staging -W ../.github/workflows/gated-deployment.yml + +# Test production approval gate +npm run act -- -j production-approval-gate -W ../.github/workflows/gated-deployment.yml + +# Test production deployment (requires approval simulation) +npm run act -- -j deploy-production -W ../.github/workflows/gated-deployment.yml +``` + +## Testing Complete Workflows + +### Test Entire Gated CI Workflow + +```bash +# Simulate pull request event +npm run act pull_request -W ../.github/workflows/gated-ci.yml + +# Simulate push to main event +npm run act push -W ../.github/workflows/gated-ci.yml +``` + +### Test Entire Gated Deployment Workflow + +```bash +# Simulate push to main (triggers staging) +npm run act push -W ../.github/workflows/gated-deployment.yml + +# Simulate manual production deployment +npm run act workflow_dispatch -W ../.github/workflows/gated-deployment.yml \ + --input environment=production +``` + +## Creating Event Files + +For testing workflows that need specific event data, create JSON event files: + +### `pr-event.json` (Pull Request Event) + +```json +{ + "pull_request": { + "number": 1, + "head": { + "sha": "abc123def456", + "ref": "feature/test-branch" + }, + "base": { + "ref": "main" + }, + "state": "open", + "draft": false + }, + "issue": { + "number": 1 + } +} +``` + +### `push-event.json` (Push Event) + +```json +{ + "ref": "refs/heads/main", + "repository": { + "default_branch": "main" + } +} +``` + +### `workflow-dispatch-event.json` (Manual Trigger) + +```json +{ + "inputs": { + "environment": "production", + "skip_tests": false + } +} +``` + +## Testing with Event Files + +```bash +# Test with PR event +npm run act pull_request -W ../.github/workflows/gated-ci.yml \ + -e pr-event.json + +# Test with push event +npm run act push -W ../.github/workflows/gated-deployment.yml \ + -e push-event.json + +# Test with workflow dispatch +npm run act workflow_dispatch -W ../.github/workflows/gated-deployment.yml \ + -e workflow-dispatch-event.json +``` + +## Debugging + +### Verbose Output + +```bash +# Run with verbose output +npm run act -- -j gate-1-start -W ../.github/workflows/gated-ci.yml -v +``` + +### Dry Run + +```bash +# Show what would run without executing +npm run act -- -W ../.github/workflows/gated-ci.yml -n +``` + +### Container Shell Access + +```bash +# Open shell in workflow container for debugging +npm run act -- -j lint -W ../.github/workflows/gated-ci.yml \ + --container-architecture linux/amd64 \ + --bind +``` + +## Common Issues + +### Issue: "Error: unable to get git diff" + +**Solution:** Ensure you're running from the repository root or specify the correct path. + +```bash +# Run from repository root +cd /home/runner/work/metabuilder/metabuilder +act -W .github/workflows/gated-ci.yml +``` + +### Issue: "Error: Job 'X' depends on job 'Y' which is not in the workflow" + +**Solution:** Test dependent jobs together or test the entire workflow. + +```bash +# Instead of testing individual jobs with dependencies, +# test the entire workflow +npm run act pull_request -W ../.github/workflows/gated-ci.yml +``` + +### Issue: Secrets not available + +**Solution:** Create a `.secrets` file or pass secrets via command line. + +```bash +# Create .secrets file +echo "DATABASE_URL=file:./dev.db" > .secrets + +# Use with act +npm run act -- -W ../.github/workflows/gated-ci.yml --secret-file .secrets +``` + +### Issue: Platform architecture mismatch (Apple Silicon) + +**Solution:** Use the correct container architecture. + +```bash +# For Apple Silicon Macs +npm run act -- -W ../.github/workflows/gated-ci.yml \ + --container-architecture linux/amd64 +``` + +## Configuration File + +Create `.actrc` in repository root for default settings: + +```bash +# .actrc +--container-architecture linux/amd64 +--secret-file .secrets +-P ubuntu-latest=catthehacker/ubuntu:act-latest +``` + +## Validation Checklist + +Before submitting a PR, test these scenarios: + +- [ ] Gate 1 passes (Prisma, TypeScript, Lint, Security) +- [ ] Gate 2 passes (Unit, E2E, DBAL Daemon tests) +- [ ] Gate 3 passes (Build, Quality checks) +- [ ] Complete workflow runs successfully on PR event +- [ ] Auto-merge workflow detects gated checks correctly +- [ ] Deployment workflow triggers on push to main + +```bash +# Quick validation script +cd frontends/nextjs + +echo "Testing Gate 1..." +npm run act -- -j gate-1-complete -W ../.github/workflows/gated-ci.yml + +echo "Testing Gate 2..." +npm run act -- -j gate-2-complete -W ../.github/workflows/gated-ci.yml + +echo "Testing Gate 3..." +npm run act -- -j gate-3-complete -W ../.github/workflows/gated-ci.yml + +echo "Testing complete workflow..." +npm run act pull_request -W ../.github/workflows/gated-ci.yml + +echo "✅ All gates validated locally!" +``` + +## Performance Tips + +### Use Docker Layer Caching + +```bash +# Pull images beforehand +docker pull catthehacker/ubuntu:act-latest + +# This speeds up subsequent runs +``` + +### Test Changed Jobs Only + +```bash +# If you only changed lint configuration, test just that gate +npm run act -- -j lint -W ../.github/workflows/gated-ci.yml +``` + +### Use GitHub Cache + +```bash +# Enable caching to speed up dependency installation +npm run act -- -W ../.github/workflows/gated-ci.yml --use-gitignore +``` + +## Resources + +- [act Documentation](https://github.com/nektos/act) +- [GitHub Actions Events](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows) +- [Workflow Syntax](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) +- [Enterprise Gated Workflow Guide](../docs/ENTERPRISE_GATED_WORKFLOW.md) + +## Getting Help + +1. Check act logs for error details +2. Verify workflow YAML syntax +3. Test individual jobs before full workflow +4. Review GitHub Actions documentation +5. Ask team for assistance + +--- + +**Last Updated:** December 27, 2025 diff --git a/docs/todo/core/21-SDLC-TODO.md b/docs/todo/core/21-SDLC-TODO.md index 94a529c81..a7c759fd0 100644 --- a/docs/todo/core/21-SDLC-TODO.md +++ b/docs/todo/core/21-SDLC-TODO.md @@ -87,7 +87,8 @@ - [ ] Create conflict notification system ### Workflow: `auto-merge.yml` -- [ ] Validate auto-merge conditions are correct +- [x] Validate auto-merge conditions are correct +- [x] Updated to support both legacy and enterprise gated workflows - [ ] Add merge queue support - [ ] Implement merge window configuration - [ ] Create merge analytics tracking @@ -98,25 +99,25 @@ ## Phase 5: Deployment ### Workflow: `deployment.yml` -- [ ] Complete pre-deployment validation checks -- [ ] Test breaking change detection -- [ ] Validate deployment notes generation -- [ ] Add environment-specific deployment paths +- [x] Complete pre-deployment validation checks (enterprise gated workflow) +- [x] Test breaking change detection (enterprise gated workflow) +- [x] Validate deployment notes generation (enterprise gated workflow) +- [x] Add environment-specific deployment paths (enterprise gated workflow) - [ ] Implement blue-green deployment support ### Deployment Safety -- [ ] Add database migration validation +- [x] Add database migration validation (enterprise gated workflow) - [ ] Implement feature flag integration - [ ] Create canary deployment support -- [ ] Add automated rollback triggers -- [ ] Implement deployment approval gates +- [x] Add automated rollback triggers (enterprise gated workflow) +- [x] Implement deployment approval gates (enterprise gated workflow - production requires manual approval) ### Monitoring Integration -- [ ] Create deployment health check automation +- [x] Create deployment health check automation (enterprise gated workflow) - [ ] Add performance regression detection - [ ] Implement error rate monitoring post-deploy - [ ] Create deployment success metrics -- [ ] Add 48-hour monitoring issue automation +- [x] Add 48-hour monitoring issue automation (enterprise gated workflow - 24hr) ---