GitHub Branch Protection Guide: Preventing Direct Commits to Main

Learn to secure your codebase with GitHub branch protection rules to prevent direct pushes to main, enforce pull request reviews.

Introduction

Branch protection rules are essential for maintaining code quality and preventing accidental or unauthorized changes to important branches like main. This guide will walk you through setting up branch protection rules in GitHub and ensuring they're properly enforced across your organization.

Setting Up Branch Protection Rules

Basic Branch Protection

1. Navigate to your repository on GitHub

2. Click on "Settings" in the top navigation bar

3. In the left sidebar, click on "Branches"

4. Under "Branch protection rules," click "Add rule"

5. In the "Branch name pattern" field, enter main (or your default branch name)

6. Check the following options:

   • "Require a pull request before merging"

   • "Require approvals" (set the number of required reviewers, typically at least 1)

   • "Dismiss stale pull request approvals when new commits are pushed"

   • "Require status checks to pass before merging"

   • "Require branches to be up to date before merging"

Under "Rules applied to everyone including administrators", check "Do not allow bypassing the above settings"

Advanced Protection Settings

For stronger protection:

1. Enable "Include administrators" to apply rules to everyone

2. Check "Restrict who can push to matching branches" if you want only specific teams/people to merge PRs

3. Enable "Allow force pushes" only for specific people/teams if absolutely necessary

Enforcing Organization-Wide Branch Protection

To ensure consistent protection across all repositories:

Using Organization Repository Rules

1. Navigate to your GitHub organization

2. Click on "Settings" in the top navigation menu

3. In the left sidebar, click on "Repository rules"

4. Click "New rule"

5. Name your rule (e.g., "Main Branch Protection")

6. Under "Branch protections", configure the same settings as above

7. Set the rule to apply to:

   • All repositories, or

   • Repositories matching specific criteria (e.g., visibility, topics)

8. Click "Create rule"

Using GitHub Enterprise Policies (For Enterprise Accounts)

If you have GitHub Enterprise:

1. Go to your enterprise account settings

2. Navigate to "Policies" > "Repository"

3. Under "Repository policies", scroll to "Branch protection rules"

4. Enable "Require branch protection rules" and configure the default settings

5. Save your changes

Verifying Branch Protection

To ensure your protections are working correctly:

1. Try pushing directly to the main branch from a local repository

   git checkout maingit commit -m "Test commit"git push

   This should be rejected with an error message

1. Create a new branch, commit changes, and open a pull request

   git checkout -b feature-branchgit commit -m "Test PR"
   git push -u origin feature-branch

   Then create a PR in the GitHub UI

2. Attempt to merge the PR without meeting requirements (this should be blocked)

Troubleshooting Common Issues

• Settings not applying: Verify "Include administrators" is checked

• Bypassed protections: Check that "Do not allow bypassing the above settings" is enabled

• Repository-specific exceptions: Review organization rules for conflicts

• Branch deletion issues: Enable "Restrict deletions" in branch protection settings

Best Practices

• Protect all production branches (main, production, etc.)

• Require at least one review for all PRs

• Configure required status checks for CI/CD pipelines

• Consider requiring signed commits for additional security

• Regularly audit branch protection settings across repositories

• Document your branch protection strategy for team reference

By implementing these protections, you'll help ensure code quality and prevent accidental deployments to critical branches.