GitHub Branch Protection Setup Guide

Overview

This document explains how to configure branch protection rules for CAIRL repository.

Main Branch Protection

Settings → Branches → Add Rule

Branch name pattern: main

Required Settings

Require Pull Request

  • ✅ Require a pull request before merging
    • ✅ Require approvals: 1
    • ✅ Dismiss stale pull request approvals when new commits are pushed
    • ✅ Require review from Code Owners

Status Checks

  • ✅ Require status checks to pass before merging
    • ✅ Require branches to be up to date before merging
    • Required status checks:
      • lint (GitHub Actions)
      • type-check (GitHub Actions)
      • build (GitHub Actions)
      • vercel (Vercel bot)

Additional Rules

  • ✅ Require conversation resolution before merging
  • ✅ Require linear history (prevents merge commits)
  • ✅ Include administrators (applies rules to admins too)

Restrictions

  • ✅ Restrict who can push to matching branches
    • Allow: No one (PRs only)
  • ❌ Allow force pushes: Disabled
  • ❌ Allow deletions: Disabled

Staging Branch Protection

Branch name pattern: staging

Settings (Same as main, except):

  • ⚠️ Require approvals: 0 (allows self-merge for testing)
  • ✅ All other settings same as main

Develop Branch Protection

Branch name pattern: develop

Settings (Same as staging):

  • ⚠️ Require approvals: 0
  • ✅ All other settings same as main

Setup Instructions

Step 1: Navigate to Settings

  1. Go to GitHub repository
  2. Click Settings (gear icon)
  3. Click Branches (left sidebar)

Step 2: Add Main Branch Rule

  1. Click Add branch protection rule
  2. Enter branch name pattern: main
  3. Enable all required settings listed above
  4. Click Create at bottom

Step 3: Add Staging Branch Rule

  1. Click Add branch protection rule
  2. Enter branch name pattern: staging
  3. Enable same settings, but set approvals to 0
  4. Click Create

Step 4: Add Develop Branch Rule

  1. Click Add branch protection rule
  2. Enter branch name pattern: develop
  3. Enable same settings as staging
  4. Click Create

Verification

Test Main Branch Protection

# This should FAIL (direct push blocked)
git checkout main
git commit --allow-empty -m "test"
git push origin main
# Expected: "Protected branch update failed"

# This should WORK (via PR)
git checkout -b test-protection
git commit --allow-empty -m "feat(test): verify protection"
git push origin test-protection
# Create PR on GitHub → should allow merge after checks

Test Status Checks

  1. Create a PR with intentional lint error
  2. CI should fail
  3. PR should be blocked from merging
  4. Fix error
  5. CI should pass
  6. PR should allow merging

Status Check Configuration

GitHub Actions (Already configured via .github/workflows/)

  • lint: ESLint validation
  • type-check: TypeScript compilation
  • build: Next.js build test

Vercel (Auto-configured when connected)

  • vercel: Deployment preview

Updating Rules

If you need to modify protection rules:

  1. Go to Settings → Branches
  2. Find the rule
  3. Click Edit
  4. Make changes
  5. Click Save changes

Bypassing Protection (Emergency Only)

Temporarily Disable Protection

  1. Settings → Branches → Find rule
  2. Click Edit
  3. Uncheck rules temporarily
  4. Make emergency change
  5. IMMEDIATELY re-enable rules

⚠️ WARNING: Only do this for critical production hotfixes. Document reason in commit.

Branch Protection Best Practices

  1. Never disable protection permanently
  2. Test changes in develop/staging first
  3. Always use PRs, even for admins
  4. Keep status checks strict
  5. Require conversation resolution
  6. No force pushes, ever
  7. Review protection settings quarterly

Troubleshooting

"Required status checks not found"

Status checks must exist before requiring them:

  1. Create a PR first (triggers CI)
  2. Let CI run once
  3. Then add to required checks

"Unable to merge: Reviews required"

Need approval from another team member. For solo dev:

  • Staging/develop allow self-merge
  • Main requires external review (add collaborator or adjust setting)

"Branch is out of date"

git checkout your-branch
git merge develop
git push

References