# Branch Protection Configuration
# This file documents the required branch protection settings to prevent validation bypasses
# GitHub CLI commands to configure branch protection:
# Main branch protection (Production)
gh api repos/:owner/:repo/branches/main/protection \
--method PUT \
--field required_status_checks='{"strict":true,"contexts":["PR Size Validation / Validate PR Size and Quality","Comprehensive Testing / Quick Validation (Unit + Smoke)","Comprehensive Testing / Server Lifecycle Testing","Comprehensive Testing / MCP Protocol Integration (18, 20, 22)","Comprehensive Testing / Security & Dependency Scan"]}' \
--field enforce_admins=false \
--field required_pull_request_reviews='{"required_approving_review_count":1,"dismiss_stale_reviews":true,"require_code_owner_reviews":false,"require_last_push_approval":false}' \
--field restrictions=null \
--field allow_force_pushes=false \
--field allow_deletions=false \
--field block_creations=false
# Test branch protection (Pre-production)
gh api repos/:owner/:repo/branches/test/protection \
--method PUT \
--field required_status_checks='{"strict":true,"contexts":["PR Size Validation / Validate PR Size and Quality","Comprehensive Testing / Quick Validation (Unit + Smoke)","Comprehensive Testing / Server Lifecycle Testing","Comprehensive Testing / MCP Protocol Integration (18, 20, 22)"]}' \
--field enforce_admins=false \
--field required_pull_request_reviews='{"required_approving_review_count":1,"dismiss_stale_reviews":true,"require_code_owner_reviews":false,"require_last_push_approval":false}' \
--field restrictions=null \
--field allow_force_pushes=false \
--field allow_deletions=false \
--field block_creations=false
# Protection Rules Explanation:
## Required Status Checks
status_checks:
# CRITICAL: PR Size Validation prevents massive PRs like #34
- name: "PR Size Validation / Validate PR Size and Quality"
description: "Prevents PRs >15,000 changes, enforces quality gates"
required: true
# CRITICAL: Quick validation catches immediate failures
- name: "Comprehensive Testing / Quick Validation (Unit + Smoke)"
description: "TypeScript, ESLint, and smoke tests must pass"
required: true
# IMPORTANT: Lifecycle testing validates MCP protocol compliance
- name: "Comprehensive Testing / Server Lifecycle Testing"
description: "Full server lifecycle and tool coordination tests"
required: true
# IMPORTANT: Cross-platform compatibility validation
- name: "Comprehensive Testing / MCP Protocol Integration (18, 20, 22)"
description: "Node.js 18, 20, 22 compatibility validation"
required: true
# SECURITY: Dependency and security scanning
- name: "Comprehensive Testing / Security & Dependency Scan"
description: "npm audit and security vulnerability scanning"
required: true # Only required for main branch (production)
## Pull Request Reviews
review_requirements:
required_approving_reviews: 1
dismiss_stale_reviews: true
require_code_owner_reviews: false # Single developer repository
require_last_push_approval: false # Allow self-updates after approval
## Admin Controls
admin_settings:
enforce_admins: false # Allow admin override for emergency fixes
allow_force_pushes: false # Prevent history rewriting
allow_deletions: false # Prevent accidental branch deletion
block_creations: false # Allow normal branch creation
# Validation Bypass Prevention Strategy:
## Layer 1: Pre-commit Hooks (Local)
local_validation:
typescript_strict: true
eslint_enforcement: true
any_type_detection: true
test_coverage_check: true
## Layer 2: PR Size Validation (GitHub Actions)
pr_validation:
max_changes: 15000 # Based on PR #34 failure analysis
large_pr_threshold: 5000
max_files_changed: 50
quality_gates_required: true
## Layer 3: Comprehensive Testing (GitHub Actions)
ci_validation:
unit_tests: required
smoke_tests: required
integration_tests: required
type_checking: required
lint_checking: required
security_scanning: required
## Layer 4: Branch Protection (GitHub API)
branch_protection:
required_status_checks: all_contexts_must_pass
pull_request_reviews: minimum_one_approval
admin_enforcement: emergency_override_only
## Layer 5: Human Review (Code Review)
human_validation:
business_logic_review: required
architecture_review: for_large_changes
security_review: for_sensitive_changes
qa_sign_off: for_test_infrastructure
# Emergency Procedures:
## Validation System Failure
emergency_bypass:
procedure: "Use admin override with detailed justification"
documentation: "Create issue explaining bypass reason"
follow_up: "Fix validation system before next merge"
audit_trail: "Log all admin overrides for review"
## Critical Security Fix
security_emergency:
procedure: "Use --admin flag on gh pr merge command"
notification: "Alert security team immediately"
documentation: "Create post-incident review issue"
validation: "Run full test suite after emergency merge"
# Monitoring and Alerting:
## Bypass Detection
monitoring:
admin_overrides: "Log all instances for audit review"
failed_status_checks: "Alert on repeated failures"
large_prs: "Flag for additional review requirements"
validation_skips: "Block and require justification"
## Quality Metrics
metrics:
validation_success_rate: ">99%"
average_pr_size: "<2000 changes"
time_to_merge: "<24 hours for small PRs"
test_coverage: ">95% maintained"
# This configuration prevents validation system bypasses like PR #34 by:
# 1. Requiring all status checks to pass (no bypass)
# 2. Enforcing PR size limits to prevent massive changes
# 3. Maintaining multiple validation layers with different scopes
# 4. Providing emergency procedures with full audit trails
# 5. Monitoring bypass attempts and quality metrics
