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

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

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:

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

{
  "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:

# 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

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

2. Failed Quality Gates

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

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

   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
• Woodpecker CI Documentation
• Gitea API Documentation
• Design Principles

---

Questions? Contact the platform team or create an issue.