stack/docs/AUTOMATED-PR-MERGE.md

# Automated PR Merge System

## Overview

The Mosaic Stack automated PR merge system ensures all pull requests meet strict quality, security, and testing standards before being merged to `develop`. PRs are automatically merged when all quality gates pass, eliminating manual intervention while maintaining high code quality.

## Quality Gates

All quality gates must pass before a PR can be auto-merged:

### 1. Code Review ✅

- **Lint:** ESLint with strict rules, no warnings allowed
- **Type Safety:** TypeScript strict mode, no type errors
- **Build:** Production build must succeed
- **Pre-commit:** Automated via lint-staged (already strict)

### 2. Security Review 🔒

- **Dependency Audit:** `pnpm audit` with high severity threshold
- **Secret Scanning:** Detects hardcoded passwords, API keys, tokens
- **SAST:** Static analysis security testing (Semgrep)
- **License Compliance:** (Planned)

### 3. Quality Assurance 🧪

- **Unit Tests:** All tests must pass
- **Test Coverage:** ≥85% coverage requirement (enforced)
- **Integration Tests:** (Planned)
- **E2E Tests:** (Planned)

## How It Works

### 1. Developer Creates PR

```bash
# Create feature branch
git checkout -b feature/my-feature develop

# Make changes, commit
git add .
git commit -m "feat: add new feature"

# Push and create PR
git push -u origin feature/my-feature
tea pr create --base develop --title "feat: add new feature"
```

### 2. CI Pipeline Runs

Woodpecker CI automatically runs all quality gates:

```mermaid
graph TD
    A[PR Created] --> B[Install Dependencies]
    B --> C[Security Audit]
    B --> D[Secret Scanning]
    B --> E[SAST Scanning]
    B --> F[Lint Check]
    B --> G[Type Check]
    B --> H[Unit Tests]
    H --> I[Coverage Check]
    C --> J{All Checks Pass?}
    D --> J
    E --> J
    F --> J
    G --> J
    I --> J
    J -->|Yes| K[Build Verification]
    K --> L[Auto-Merge to develop]
    J -->|No| M[Block Merge]
```

### 3. Automatic Merge

If all checks pass:

- ✅ PR automatically merges to `develop`
- ✅ Feature branch automatically deleted
- ✅ Developer notified of successful merge

If any check fails:

- ❌ PR blocked from merging
- ❌ Developer notified of failure
- ❌ Must fix issues before retry

## Configuration

### Woodpecker CI

The enhanced Woodpecker CI configuration is in `.woodpecker.enhanced.yml`. Key features:

```yaml
# Strict quality gates (all must pass)
lint:
  failure: fail # Block on any lint error/warning

typecheck:
  failure: fail # Block on any type error

test-unit:
  failure: fail # Block on any test failure

# Security scanning
security-audit-deps:
  failure: fail # Block on high/critical vulnerabilities

security-scan-secrets:
  failure: fail # Block on hardcoded secrets

# Auto-merge step (runs after all checks pass)
pr-auto-merge:
  when:
    - event: pull_request
      evaluate: 'CI_COMMIT_TARGET_BRANCH == "develop"'
  depends_on:
    - build
    - test-unit
    - lint
    - typecheck
    - security-audit-deps
```

### Required Secrets

Configure these in Gitea settings → Secrets:

- `gitea_token` - API token with repo write access
- `gitea_username` - Gitea username for Docker registry

### Branch Protection

Recommended Gitea branch protection for `develop`:

```json
{
  "branch_name": "develop",
  "enable_push": false,
  "enable_push_whitelist": false,
  "enable_merge_whitelist": false,
  "enable_status_check": true,
  "required_status_checks": [
    "ci/woodpecker/pr/lint",
    "ci/woodpecker/pr/typecheck",
    "ci/woodpecker/pr/test-unit",
    "ci/woodpecker/pr/security-audit-deps",
    "ci/woodpecker/pr/build"
  ],
  "enable_approvals_whitelist": false,
  "required_approvals": 0
}
```

## Manual Auto-Merge

You can manually trigger auto-merge for a specific PR:

```bash
# Set Gitea API token
export GITEA_TOKEN="your-token-here"

# Merge PR #123 to develop
./scripts/ci/auto-merge-pr.sh 123

# Dry run (check without merging)
DRY_RUN=true ./scripts/ci/auto-merge-pr.sh 123
```

## Quality Gate Strictness Levels

### Current (Enhanced) Configuration

| Check            | Status    | Blocking | Notes                                    |
| ---------------- | --------- | -------- | ---------------------------------------- |
| Dependency Audit | ✅ Active | Yes      | Blocks on high+ vulnerabilities          |
| Secret Scanning  | ✅ Active | Yes      | Blocks on hardcoded secrets              |
| SAST (Semgrep)   | ⚠️ Active | No\*     | \*TODO: Enable after baseline cleanup    |
| Lint             | ✅ Active | Yes      | Zero warnings/errors                     |
| TypeScript       | ✅ Active | Yes      | Strict mode, no errors                   |
| Unit Tests       | ✅ Active | Yes      | All tests must pass                      |
| Test Coverage    | ⚠️ Active | No\*     | \*TODO: Enable after implementing parser |
| Build            | ✅ Active | Yes      | Production build must succeed            |

### Migration Plan

**Phase 1: Current State**

- Lint and tests non-blocking (`|| true`)
- Basic security audit
- Manual PR merging

**Phase 2: Enhanced (This PR)** ← WE ARE HERE

- All checks strict and blocking
- Security scanning (deps, secrets, SAST)
- Auto-merge enabled for clean PRs

**Phase 3: Future Enhancements**

- SAST fully enforced (after baseline cleanup)
- Test coverage threshold enforced (≥85%)
- Integration and E2E tests
- License compliance checking
- Performance regression testing

## Troubleshooting

### PR Not Auto-Merging

Check these common issues:

1. **Merge Conflicts**

   ```bash
   # Rebase on develop
   git fetch origin develop
   git rebase origin/develop
   git push --force-with-lease
   ```

2. **Failed Quality Gates**

   ```bash
   # Check CI logs
   woodpecker pipeline ls mosaic/stack
   woodpecker log show mosaic/stack <pipeline-number>
   ```

3. **Missing Status Checks**
   - Ensure all required checks are configured
   - Verify Woodpecker CI is running
   - Check webhook configuration

### Bypassing Auto-Merge

In rare cases where manual merge is needed:

```bash
# Manually merge via CLI (requires admin access)
tea pr merge <pr-number> --style merge
```

**⚠️ WARNING:** Manual merges bypass quality gates. Only use in emergencies.

## Best Practices

### For Developers

1. **Run checks locally before pushing:**

   ```bash
   pnpm lint
   pnpm typecheck
   pnpm test
   pnpm build
   ```

2. **Keep PRs focused:**
   - One feature/fix per PR
   - Smaller PRs merge faster
   - Easier to review and debug

3. **Write tests first (TDD):**
   - Tests before implementation
   - Maintains ≥85% coverage
   - Catches issues early

4. **Check CI status:**
   - Monitor pipeline progress
   - Fix failures immediately
   - Don't stack PRs on failing ones

### For Reviewers

1. **Trust the automation:**
   - If CI passes, code meets standards
   - Focus on architecture and design
   - Don't duplicate automated checks

2. **Review promptly:**
   - PRs auto-merge when checks pass
   - Review before auto-merge if needed
   - Use Gitea's review features

3. **Provide constructive feedback:**
   - Suggest improvements
   - Link to documentation
   - Explain reasoning

## Metrics & Monitoring

Track these metrics to measure effectiveness:

- **Auto-merge rate:** % of PRs merged automatically
- **Average time to merge:** From PR creation to merge
- **Quality gate failures:** Which checks fail most often
- **Rollback rate:** % of merges that need revert

## References

- [Quality Rails Status](docs/quality-rails-status.md)
- [Woodpecker CI Documentation](https://woodpecker-ci.org/docs)
- [Gitea API Documentation](https://docs.gitea.io/en-us/api-usage/)
- [Design Principles](docs/DESIGN-PRINCIPLES.md)

---

**Questions?** Contact the platform team or create an issue.