_private/qwestly-docs/CI-CD/Branch Protection.md

Table of Contents

Branch Protection Rules for SOC2 Compliance

Required Settings for main branch:

1. General Protection Rules

  • ✅ Require a pull request before merging
    • Require approvals: 1 minimum (can increase to 2 for additional security)
    • Dismiss stale PR approvals when new commits are pushed
    • Require review from code owners (if CODEOWNERS file exists)

2. Status Check Requirements

  • ✅ Require status checks to pass before merging
    • Require branches to be up to date before merging
    • Required status checks by repository:

qwestly-app (Main Application)

  • security-scan - Trivy vulnerability scanning
  • lint-and-test - Code quality, type checking, unit tests, E2E tests
  • compliance-checks - TruffleHog secret scanning
  • Vercel deployment checks (automatic)

candidate (Candidate Portal)

  • security-scan - Trivy vulnerability scanning
  • compliance-checks - TruffleHog secret scanning
  • Vercel deployment checks (automatic)
  • Note: lint-and-test temporarily commented out pending GitHub Packages token configuration

public-site (Public Website)

  • security-scan - Trivy vulnerability scanning
  • lint-and-test - Code quality and testing (when implemented)
  • compliance-checks - TruffleHog secret scanning
  • Vercel deployment checks (automatic)

api-python (Python Backend)

  • security-scan - Trivy vulnerability scanning
  • python-quality-checks - Black, isort, mypy, pytest, bandit security scanning
  • compliance-checks - TruffleHog secret scanning
  • Vercel deployment checks (automatic)

3. Additional Controls

  • ✅ Require linear history (optional but recommended for cleaner git history)
  • ✅ Include administrators (critical for SOC2 - no bypass privileges)
  • ✅ Restrict pushes that create files (prevents direct main branch commits)
  • ✅ Require signed commits (highly recommended for SOC2 audit trail)

4. Implementation Status by Repository

✅ Implemented Repositories

  • qwestly-app - Full branch protection active
  • candidate - Branch protection active

🔄 Pending Implementation

  • public-site - Configure when workflow is deployed
  • api-python - Configure when workflow is deployed

5. Configure in GitHub Settings

  1. Navigate to repository Settings > Branches
  2. Click Add rule for main branch
  3. Configure all protection settings listed above
  4. Save changes and test with sample PR

Environment Protection Rules

Environment protection provides additional deployment controls beyond branch protection.

Production Environment Configuration

  • Required reviewers: Minimum 1 (Adam Boender and Dominick Pham)
  • Wait timer: 0 minutes (immediate deployment after approval)
  • Bypass settings: Required reviewers can bypass wait timer ✅
  • Deployment branches: Restrict to main branch only

Staging Environment Configuration

  • No restrictions - Allows automatic preview deployments
  • Used for: PR preview deployments via Vercel integration
  • Access: All team members can trigger staging deployments

Implementation Notes

✅ Current Status

  • qwestly-app - Environment protection active for production deployments
  • candidate - Environment protection configured
  • Vercel Integration - Native GitHub integration handles actual deployments
  • GitHub Actions - Focuses on validation rather than deployment execution

🔄 Optional Enhancements

  • Deployment time windows - Restrict production deployments to business hours
  • Additional reviewers - Require multiple approvals for critical changes
  • Automated rollback triggers - Based on error rate or performance thresholds

SOC2 Compliance Mapping

Access Controls (CC6.1, CC6.2)

  • ✅ Multi-factor authentication required for all GitHub accounts
  • ✅ Role-based permissions enforced through GitHub team membership
  • ✅ Principle of least privilege via repository-specific access controls
  • ✅ Regular access reviews conducted quarterly

Change Management (CC8.1)

  • ✅ Mandatory peer reviews via pull request requirement
  • ✅ Automated quality gates via required status checks
  • ✅ Complete audit trail via Git history and GitHub Actions logs
  • ✅ Rollback capabilities via Vercel deployment history

Monitoring and Logging (CC7.1)

  • ✅ Real-time security scanning on every commit
  • ✅ Deployment monitoring via Vercel dashboards
  • ✅ Audit log retention for compliance review periods
  • ✅ Alert notifications for security findings and deployment failures

Troubleshooting Common Issues

Branch Protection Not Enforcing

  1. Verify Include administrators is enabled
  2. Check that status check names match workflow job names exactly
  3. Ensure required reviewers have appropriate repository permissions

Status Checks Failing

  1. Review GitHub Actions workflow logs for specific errors
  2. Verify all required secrets are configured in repository settings
  3. Check that workflow permissions include necessary scopes

Environment Protection Bypassed

  1. Confirm environment names match deployment configuration
  2. Verify required reviewers are correctly configured
  3. Check deployment branch restrictions are properly set

Configuration Owner: Dominick Pham, CTO
Last Updated: July 1, 2025
Next Review: October 1, 2025