Branch Protection Rules — The Hotfix That Bypassed All Reviews

Branch protection rules are the most important Git configuration you'll set up. They prevent the most common and most damaging Git mistakes: direct pushes to main, un-reviewed code reaching production, and broken builds being merged. Without protection rules, a single developer error can take down production. With them, every change to main goes through an automated gate. This guide covers the essential protection rules, the incident where a 'hotfix' bypassed all review and broke production, and how to configure branch protection for your workflow.

What Are Branch Protection Rules?

Branch protection rules are automated policies enforced by Git hosting platforms (GitHub, GitLab, Bitbucket) to prevent direct pushes, enforce code reviews, and require status checks before merging. They act as a safety net, ensuring that changes to critical branches like main or release follow a defined workflow. Without them, a single accidental push can break production. In my experience, teams that skip protection rules spend 30% more time firefighting broken builds. Protection rules are not optional—they are the first line of defense in a secure Git workflow.

name: Branch Protection
on: [push, pull_request]
jobs:
  enforce:
    runs-on: ubuntu-latest
    steps:
      - name: Check branch
        run: |
          if [[ "${{ github.ref }}" == "refs/heads/main" ]]; then
            echo "Direct push to main is blocked. Use pull requests."
            exit 1
          fi

Setting Up Required Pull Request Reviews

The most common protection rule is requiring pull request (PR) reviews before merging. This ensures at least one other developer has reviewed the code. You can configure the number of reviewers (typically 1 for small teams, 2 for critical repos) and optionally require reviews from code owners. Dismissing stale reviews when new commits are pushed is also a good practice—it forces re-review of changes. In production, I've seen teams skip this and merge unreviewed code that introduced security vulnerabilities. Always enable 'Dismiss stale pull request approvals when new commits are pushed' to keep reviews meaningful.

# Using GitHub CLI to require PR reviews on main
gh api repos/:owner/:repo/branches/main/protection \
  --method PUT \
  --field required_pull_request_reviews[required_approving_review_count]=2 \
  --field required_pull_request_reviews[dismiss_stale_reviews]=true \
  --field required_pull_request_reviews[require_code_owner_reviews]=true

Enforcing Status Checks Before Merge

Status checks are automated tests (CI, linting, security scans) that must pass before a branch can merge. Protection rules can require specific checks to pass. This prevents merging broken code. Common checks include unit tests, integration tests, and code coverage thresholds. In production, always require checks on the latest commit—not just any commit in the branch. I've seen teams merge with green checks that were from an older commit, bypassing recent failures. Use 'Require branches to be up to date' to enforce this.

name: CI
on: [pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: npm test
      - name: Check coverage
        run: npx jest --coverage --coverageThreshold='{"global":{"lines":80}}'

Blocking Direct Pushes and Force Pushes

Direct pushes to protected branches should be blocked entirely. All changes must go through PRs. Force pushes should also be blocked—they rewrite history and can cause chaos. If you need to allow force pushes for specific scenarios (e.g., temporary branches), use the 'Allow force pushes' setting with a list of users or teams. In production, I've seen force pushes used to 'fix' a merge conflict, only to lose commits. Block force pushes on main and release branches. For feature branches, consider using 'Allow force pushes' only for admins.

# Block force pushes on main branch via GitHub API
gh api repos/:owner/:repo/branches/main/protection \
  --method PUT \
  --field enforce_admins=true \
  --field required_linear_history=true \
  --field allow_force_pushes=false

Requiring Linear History and Squash Merges

Linear history means no merge commits—every commit is applied sequentially. This makes git log easier to read and simplifies bisecting. Protection rules can enforce linear history by requiring rebase or squash merges. Squash merges combine all PR commits into one, keeping history clean. In production, I prefer squash merges for feature branches and rebase for release branches. Avoid merge commits on main—they create unnecessary complexity. Use 'Require linear history' to block merge commits.

repository:
  allow_merge_commit: false
  allow_squash_merge: true
  allow_rebase_merge: true
branches:
  - name: main
    protection:
      required_linear_history: true

Setting Up Code Owners for Automatic Reviews

Code owners are individuals or teams responsible for specific files or directories. Protection rules can require code owner reviews before merging. This ensures that changes to sensitive areas (e.g., security, database migrations) are reviewed by the right experts. Define a CODEOWNERS file in the repository root. In production, use code owners for critical paths like src/auth/ or deploy/. Without this, a junior dev might modify authentication logic without a security expert reviewing it.

# Global owners
* @team-leads

# Security-critical code
/src/auth/ @security-team

# Database migrations
/db/migrations/ @dba-team

# Deployment scripts
/deploy/ @ops-team

Using Include/Exclude Patterns for Flexible Protection

Not all branches need the same level of protection. You can use include/exclude patterns to apply rules to specific branches. For example, protect main and release/ strictly, but allow more flexibility on feature/ or dev. This balances security with developer velocity. In production, I always protect main and release/* with full rules, and develop with lighter rules (e.g., require PR but not status checks). Avoid protecting every branch—it slows down experimentation.

branch_protection:
  - pattern: main
    rules:
      required_pull_request_reviews: true
      required_status_checks: true
  - pattern: release/*
    rules:
      required_pull_request_reviews: true
      required_status_checks: true
  - pattern: feature/*
    rules: {}  # no protection for feature branches

Auditing and Enforcing Protection Rules at Scale

As your organization grows, manually configuring protection rules per repository becomes unsustainable. Use automation tools like GitHub's branch protection API, Terraform, or organization-wide settings to enforce rules consistently. Regularly audit repositories to ensure compliance. In production, I've seen teams with 100+ repos where half had no protection rules. Use scripts to scan and report. Enforce rules at the organization level for critical branches like main. This prevents drift and ensures every repo meets the minimum security bar.

# Audit all repos in an org for main branch protection
gh api orgs/:org/repos --paginate | jq -r '.[].name' | while read repo; do
  protection=$(gh api repos/:org/$repo/branches/main/protection 2>/dev/null)
  if [ -z "$protection" ]; then
    echo "$repo: NO PROTECTION"
  else
    echo "$repo: PROTECTED"
  fi
done

Handling Exceptions: Bypassing Protection Rules Safely

Sometimes you need to bypass protection rules—for emergency hotfixes or admin tasks. Most platforms allow certain users or teams to bypass rules. Use this sparingly and log all bypasses. In production, I recommend a 'break glass' procedure: only a small set of senior engineers can bypass, and every bypass triggers an alert. Never give everyone bypass access. Also, consider using 'Require approval from a separate team' for bypasses. This prevents abuse while allowing urgent fixes.

name: Break Glass Alert
on:
  push:
    branches: [main]
jobs:
  alert:
    runs-on: ubuntu-latest
    steps:
      - name: Notify security
        run: |
          echo "Direct push to main by ${{ github.actor }} at $(date)" | mail -s "ALERT: Main branch bypass" security@company.com

Common Pitfalls and How to Avoid Them

Even with protection rules, teams make mistakes. Common pitfalls include: (1) Not requiring status checks on the latest commit—stale checks pass while new commits fail. (2) Allowing too many bypassers—everyone becomes an admin. (3) Overprotecting—slowing down development. (4) Ignoring code owners—reviews go to the wrong people. (5) Not auditing—rules drift over time. Avoid these by: always requiring up-to-date branches, limiting admin access, using patterns for flexible protection, maintaining CODEOWNERS, and running regular audits.

# Check if any PR has passed checks but new commits exist
gh pr list --state open --json number,headRefName,commits | jq '.[] | select(.commits[-1].committedDate > .updatedAt)'

Integrating Protection Rules with CI/CD Pipelines

Branch protection rules and CI/CD pipelines work together. The pipeline runs checks, and protection rules enforce that those checks pass before merge. For a robust setup, ensure your CI/CD pipeline reports statuses correctly. Use commit statuses (success/failure) and require specific status names. In production, I've seen pipelines that report 'success' even when tests fail due to misconfiguration. Validate your pipeline by intentionally breaking a test and ensuring the status check fails. Also, use 'Required status checks' to block merge if any required check fails.

name: Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy
        run: ./deploy.sh
      - name: Update status
        run: |
          gh api repos/${{ github.repository }}/statuses/${{ github.sha }} \
            --field state=success --field context=deploy

Advanced: Using Protection Rules for Compliance and Auditing

In regulated industries, branch protection rules can help meet compliance requirements like SOC2, PCI-DSS, or HIPAA. For example, require two-factor authentication for merging, enforce signed commits, or require a specific number of approvals. You can also require that PRs include a reference to a ticket (e.g., JIRA issue). Protection rules provide an audit trail of who merged what and when. In production, I've used protection rules to enforce that all merges to main have a corresponding change request approved by a compliance officer.

name: Compliance Check
on:
  pull_request:
    types: [opened, edited]
jobs:
  check-ticket:
    runs-on: ubuntu-latest
    steps:
      - name: Check for JIRA ticket
        run: |
          if ! echo "${{ github.event.pull_request.body }}" | grep -qE '[A-Z]+-[0-9]+'; then
            echo "PR must include a JIRA ticket reference in the description."
            exit 1
          fi