stack/docs/MIGRATION-AUTO-MERGE.md

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

  # 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

  # 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

# 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

# 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:

# 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:

# 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

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

# 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:

# 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

# 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:

# 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

  # 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:

# 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:

# 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:

# 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
• Issues: https://git.mosaicstack.dev/mosaic/stack/issues
• Team Chat: #engineering on Mattermost

---

Migration Owner: Platform Team Last Updated: 2026-02-03