feat: Implement automated PR merging with comprehensive quality gates
Some checks failed
ci/woodpecker/push/woodpecker Pipeline failed
Some checks failed
ci/woodpecker/push/woodpecker Pipeline failed
Add automated PR merge system with strict quality gates ensuring code review, security review, and QA completion before merging to develop. Features: - Enhanced Woodpecker CI with strict quality gates - Automatic PR merging when all checks pass - Security scanning (dependency audit, secrets, SAST) - Test coverage enforcement (≥85%) - Comprehensive documentation and migration guide Quality Gates: ✅ Lint (strict, blocking) ✅ TypeScript (strict, blocking) ✅ Build verification (strict, blocking) ✅ Security audit (strict, blocking) ✅ Secret scanning (strict, blocking) ✅ SAST (Semgrep, currently non-blocking) ✅ Unit tests (strict, blocking) ⚠️ Test coverage (≥85%, planned) Auto-Merge: - Triggers when all quality gates pass - Only for PRs targeting develop - Automatically deletes source branch - Notifies on success/failure Files Added: - .woodpecker.enhanced.yml - Enhanced CI configuration - scripts/ci/auto-merge-pr.sh - Standalone merge script - docs/AUTOMATED-PR-MERGE.md - Complete documentation - docs/MIGRATION-AUTO-MERGE.md - Migration guide Migration Plan: Phase 1: Enhanced CI active, auto-merge in dry-run Phase 2: Enable auto-merge for clean PRs Phase 3: Enforce test coverage threshold Phase 4: Full enforcement (SAST blocking) Benefits: - Zero manual intervention for clean PRs - Strict quality maintained (85% coverage, no errors) - Security vulnerabilities caught before merge - Faster iteration (auto-merge within minutes) - Clear feedback (detailed quality gate results) Next Steps: 1. Review .woodpecker.enhanced.yml configuration 2. Test with dry-run PR 3. Configure branch protection for develop 4. Gradual rollout per migration guide Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
366
docs/MIGRATION-AUTO-MERGE.md
Normal file
366
docs/MIGRATION-AUTO-MERGE.md
Normal file
@@ -0,0 +1,366 @@
|
||||
# Migration Guide: Enhanced CI/CD with Auto-Merge
|
||||
|
||||
## Overview
|
||||
|
||||
This guide walks through migrating from the current Woodpecker CI configuration to the enhanced version with strict quality gates and automated PR merging.
|
||||
|
||||
## Pre-Migration Checklist
|
||||
|
||||
Before activating the enhanced pipeline, ensure:
|
||||
|
||||
- [ ] **All existing PRs are merged or closed**
|
||||
- Enhanced pipeline has strict gates that may block old PRs
|
||||
- Review and clean up pending PRs first
|
||||
|
||||
- [ ] **Baseline quality metrics recorded**
|
||||
|
||||
```bash
|
||||
# Run on clean develop branch
|
||||
pnpm lint 2>&1 | tee baseline-lint.txt
|
||||
pnpm typecheck 2>&1 | tee baseline-typecheck.txt
|
||||
pnpm test 2>&1 | tee baseline-tests.txt
|
||||
```
|
||||
|
||||
- [ ] **Gitea API token created**
|
||||
- Go to Settings → Applications → Generate New Token
|
||||
- Scopes: `repo` (full control)
|
||||
- Save token securely
|
||||
|
||||
- [ ] **Woodpecker secrets configured**
|
||||
|
||||
```bash
|
||||
# Add gitea_token secret
|
||||
woodpecker secret add \
|
||||
--repository mosaic/stack \
|
||||
--name gitea_token \
|
||||
--value "your-token-here"
|
||||
```
|
||||
|
||||
- [ ] **Team notified of change**
|
||||
- Announce strict quality gates
|
||||
- Share this migration guide
|
||||
- Schedule migration during low-activity period
|
||||
|
||||
## Migration Steps
|
||||
|
||||
### Step 1: Backup Current Configuration
|
||||
|
||||
```bash
|
||||
# Backup current .woodpecker.yml
|
||||
cp .woodpecker.yml .woodpecker.yml.backup
|
||||
|
||||
# Backup current git state
|
||||
git branch backup-pre-migration
|
||||
git push origin backup-pre-migration
|
||||
```
|
||||
|
||||
### Step 2: Activate Enhanced Configuration
|
||||
|
||||
```bash
|
||||
# Replace .woodpecker.yml with enhanced version
|
||||
cp .woodpecker.enhanced.yml .woodpecker.yml
|
||||
|
||||
# Review changes
|
||||
git diff .woodpecker.yml.backup .woodpecker.yml
|
||||
```
|
||||
|
||||
Key changes:
|
||||
|
||||
- ✅ Removed `|| true` from lint step (now strict)
|
||||
- ✅ Removed `|| true` from test step (now strict)
|
||||
- ✅ Added security scanning steps
|
||||
- ✅ Added test coverage step
|
||||
- ✅ Added pr-auto-merge step
|
||||
|
||||
### Step 3: Test with a Dry-Run PR
|
||||
|
||||
Create a test PR to verify the enhanced pipeline:
|
||||
|
||||
```bash
|
||||
# Create test branch
|
||||
git checkout -b test/enhanced-ci develop
|
||||
|
||||
# Make a trivial change
|
||||
echo "# CI Test" >> README.md
|
||||
git add README.md
|
||||
git commit -m "test: verify enhanced CI pipeline"
|
||||
|
||||
# Push and create PR
|
||||
git push -u origin test/enhanced-ci
|
||||
tea pr create \
|
||||
--base develop \
|
||||
--title "test: Verify enhanced CI pipeline" \
|
||||
--description "Test PR to verify all quality gates work correctly"
|
||||
```
|
||||
|
||||
Monitor the pipeline:
|
||||
|
||||
```bash
|
||||
# Watch pipeline status
|
||||
woodpecker pipeline ls mosaic/stack
|
||||
|
||||
# View logs if needed
|
||||
woodpecker log show mosaic/stack <pipeline-number>
|
||||
```
|
||||
|
||||
Expected behavior:
|
||||
|
||||
- ✅ All quality gates run
|
||||
- ✅ Security scans complete
|
||||
- ✅ Tests and coverage checks run
|
||||
- ✅ PR auto-merges if all checks pass
|
||||
|
||||
### Step 4: Configure Branch Protection
|
||||
|
||||
Set up branch protection for `develop`:
|
||||
|
||||
**Option A: Via Gitea Web UI**
|
||||
|
||||
1. Go to Settings → Branches
|
||||
2. Add branch protection rule for `develop`
|
||||
3. Enable: "Enable Status Check"
|
||||
4. Add required checks:
|
||||
- `ci/woodpecker/pr/lint`
|
||||
- `ci/woodpecker/pr/typecheck`
|
||||
- `ci/woodpecker/pr/test-unit`
|
||||
- `ci/woodpecker/pr/security-audit-deps`
|
||||
- `ci/woodpecker/pr/build`
|
||||
|
||||
**Option B: Via API**
|
||||
|
||||
```bash
|
||||
curl -X POST "https://git.mosaicstack.dev/api/v1/repos/mosaic/stack/branch_protections" \
|
||||
-H "Authorization: token $GITEA_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"branch_name": "develop",
|
||||
"enable_push": false,
|
||||
"enable_status_check": true,
|
||||
"status_check_contexts": [
|
||||
"ci/woodpecker/pr/lint",
|
||||
"ci/woodpecker/pr/typecheck",
|
||||
"ci/woodpecker/pr/test-unit",
|
||||
"ci/woodpecker/pr/security-audit-deps",
|
||||
"ci/woodpecker/pr/build"
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
### Step 5: Gradual Rollout
|
||||
|
||||
**Phase 1: Monitor (Week 1)**
|
||||
|
||||
- Enhanced CI active, auto-merge disabled
|
||||
- Monitor quality gate failures
|
||||
- Collect metrics on pass/fail rates
|
||||
|
||||
```yaml
|
||||
# In .woodpecker.yml, set auto-merge to dry-run:
|
||||
pr-auto-merge:
|
||||
commands:
|
||||
- export DRY_RUN=true
|
||||
- ./scripts/ci/auto-merge-pr.sh
|
||||
```
|
||||
|
||||
**Phase 2: Enable Auto-Merge (Week 2)**
|
||||
|
||||
- Remove DRY_RUN flag
|
||||
- Enable auto-merge for clean PRs
|
||||
- Monitor merge success rate
|
||||
|
||||
**Phase 3: Enforce Coverage (Week 3)**
|
||||
|
||||
- Enable test coverage threshold
|
||||
- Set minimum to 85%
|
||||
- Block PRs below threshold
|
||||
|
||||
**Phase 4: Full Enforcement (Week 4)**
|
||||
|
||||
- Enable SAST as blocking
|
||||
- Enforce all quality gates
|
||||
- Remove any remaining fallbacks
|
||||
|
||||
### Step 6: Cleanup
|
||||
|
||||
After successful migration:
|
||||
|
||||
```bash
|
||||
# Remove backup files
|
||||
rm .woodpecker.yml.backup
|
||||
git branch -D backup-pre-migration
|
||||
git push origin --delete backup-pre-migration
|
||||
|
||||
# Remove old test PR
|
||||
tea pr close <test-pr-number>
|
||||
```
|
||||
|
||||
## Rollback Plan
|
||||
|
||||
If issues arise during migration:
|
||||
|
||||
### Immediate Rollback
|
||||
|
||||
```bash
|
||||
# Restore original configuration
|
||||
cp .woodpecker.yml.backup .woodpecker.yml
|
||||
git add .woodpecker.yml
|
||||
git commit -m "rollback: Restore original CI configuration"
|
||||
git push origin develop
|
||||
```
|
||||
|
||||
### Partial Rollback
|
||||
|
||||
If only specific gates are problematic:
|
||||
|
||||
```yaml
|
||||
# Make specific checks non-blocking temporarily
|
||||
lint:
|
||||
commands:
|
||||
- pnpm lint || true # Non-blocking during stabilization
|
||||
failure: ignore
|
||||
```
|
||||
|
||||
## Post-Migration Verification
|
||||
|
||||
After migration, verify:
|
||||
|
||||
- [ ] **All quality gates run on PRs**
|
||||
|
||||
```bash
|
||||
# Check recent PR pipelines
|
||||
tea pr list --state all --limit 10
|
||||
```
|
||||
|
||||
- [ ] **Auto-merge works correctly**
|
||||
- Create test PR with passing checks
|
||||
- Verify auto-merge occurs
|
||||
- Check branch deletion
|
||||
|
||||
- [ ] **Failures block correctly**
|
||||
- Create test PR with lint errors
|
||||
- Verify PR is blocked
|
||||
- Verify error messages are clear
|
||||
|
||||
- [ ] **Metrics tracked**
|
||||
- Auto-merge rate
|
||||
- Average time to merge
|
||||
- Quality gate failure rate
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Issue: PRs not auto-merging
|
||||
|
||||
**Diagnosis:**
|
||||
|
||||
```bash
|
||||
# Check if pr-auto-merge step ran
|
||||
woodpecker log show mosaic/stack <pipeline> | grep "pr-auto-merge"
|
||||
|
||||
# Check Gitea token permissions
|
||||
curl -H "Authorization: token $GITEA_TOKEN" \
|
||||
https://git.mosaicstack.dev/api/v1/user
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. Verify `gitea_token` secret is configured
|
||||
2. Check token has `repo` scope
|
||||
3. Ensure PR targets `develop`
|
||||
4. Verify all dependencies passed
|
||||
|
||||
### Issue: Quality gates failing unexpectedly
|
||||
|
||||
**Diagnosis:**
|
||||
|
||||
```bash
|
||||
# Run checks locally
|
||||
pnpm lint
|
||||
pnpm typecheck
|
||||
pnpm test
|
||||
|
||||
# Compare with baseline
|
||||
diff baseline-lint.txt <(pnpm lint 2>&1)
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. Fix actual code issues
|
||||
2. Update baseline if needed
|
||||
3. Temporarily make check non-blocking
|
||||
4. Investigate CI environment differences
|
||||
|
||||
### Issue: Security scans too strict
|
||||
|
||||
**Diagnosis:**
|
||||
|
||||
```bash
|
||||
# Run security scan locally
|
||||
pnpm audit --audit-level=high
|
||||
|
||||
# Check specific vulnerability
|
||||
pnpm audit --json | jq '.vulnerabilities'
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. Update dependencies: `pnpm update`
|
||||
2. Add audit exceptions if false positive
|
||||
3. Lower severity threshold temporarily
|
||||
4. Fix actual vulnerabilities
|
||||
|
||||
## Success Criteria
|
||||
|
||||
Migration is successful when:
|
||||
|
||||
- ✅ **100% of clean PRs auto-merge**
|
||||
- No manual intervention needed
|
||||
- Merge within 5 minutes of CI completion
|
||||
|
||||
- ✅ **Zero false-positive blocks**
|
||||
- All blocked PRs have actual issues
|
||||
- No spurious failures
|
||||
|
||||
- ✅ **Developer satisfaction high**
|
||||
- Fast feedback loops
|
||||
- Clear error messages
|
||||
- Minimal friction
|
||||
|
||||
- ✅ **Quality maintained or improved**
|
||||
- No increase in bugs reaching develop
|
||||
- Test coverage ≥85%
|
||||
- Security vulnerabilities caught early
|
||||
|
||||
## Next Steps
|
||||
|
||||
After successful migration:
|
||||
|
||||
1. **Monitor and optimize**
|
||||
- Track metrics weekly
|
||||
- Identify bottlenecks
|
||||
- Optimize slow steps
|
||||
|
||||
2. **Expand coverage**
|
||||
- Add integration tests
|
||||
- Add E2E tests
|
||||
- Add performance tests
|
||||
|
||||
3. **Enhance security**
|
||||
- Enable SAST fully
|
||||
- Add license compliance
|
||||
- Add container scanning
|
||||
|
||||
4. **Improve developer experience**
|
||||
- Add pre-push hooks
|
||||
- Create quality dashboard
|
||||
- Automate changelog generation
|
||||
|
||||
## Support
|
||||
|
||||
- **Documentation:** [docs/AUTOMATED-PR-MERGE.md](AUTOMATED-PR-MERGE.md)
|
||||
- **Issues:** https://git.mosaicstack.dev/mosaic/stack/issues
|
||||
- **Team Chat:** #engineering on Mattermost
|
||||
|
||||
---
|
||||
|
||||
**Migration Owner:** Platform Team
|
||||
**Last Updated:** 2026-02-03
|
||||
Reference in New Issue
Block a user