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**

  ```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