How to set up branch protection rules in GitHub

Branch protection rules are a feature in version control systems like GitHub. They allow repository administrators to enforce certain conditions that must be met before changes can be merged into specific branches. These rules safeguard branches, particularly the main branch, from unreviewed changes and make sure that specific workflows, such as code reviews and status checks, are followed. In this guide, we’ll walk through how to set up branch protection rules in GitHub and discuss why these rules are essential for teams managing collaborative development.

Why set up branch protection rules in GitHub?

The ability to enforce branch protection in GitHub is critical for teams who want to:

• Prevent accidental merges of unreviewed or buggy code.
• Enforce code review workflows.
• Ensure that tests are passing before code is merged.
• Block force pushes that can rewrite branch history.
• Require signed commits for additional security.

How to set up branch protection rules in GitHub

Here’s a step-by-step process to set up branch protection rules in GitHub:

Step 1: Navigate to your repository settings

• Go to the GitHub repository where you want to enforce branch protection.
• On the repository’s page, click on the Settings tab (this is visible to repository administrators or owners).

Step 2: Access the branch protection rules section

• In the Settings tab, scroll down to the Code and automation section on the left sidebar.
• Click on Branches.
• Under the Branch protection rules heading, click on Add rule. This will open a form where you can configure the rules for a specific branch.

Step 3: Define the branch protection rule

6. In the Branch name pattern field, specify which branch or branches the rules will apply to. For example:
   • Use main to protect the main branch.
   • Use wildcard patterns like release/* to protect all release branches.
7. Enable the necessary branch protection GitHub options based on your team’s workflow.

Step 4: Customize branch protection options

Here are some common settings:

• Require a pull request before merging

  Enabling this setting ensures that all changes must go through a pull request, making it easier to enforce code review workflows.

• Require approvals

  You can enforce that pull requests need to be approved by a specific number of reviewers (e.g., at least one or two approvals). This is especially important for ensuring code quality and knowledge sharing.

• Require status checks to pass before merging

  This option ensures that specific automated checks, such as continuous integration (CI) tests or linters, must pass before the pull request can be merged. You can select which checks to enforce.

• Require signed commits

  If security is a concern, requiring signed commits ensures that each commit is verified by a contributor's GPG key.

• Require linear history

  Enabling this option prevents merge commits, enforcing a cleaner commit history where each change is replayed sequentially on the branch.

• Do not allow force pushes

  This prevents contributors from force-pushing changes to the protected branch, which can rewrite commit history and lead to potential loss of important data.

• Do not allow deletions

  This option ensures the branch cannot be accidentally deleted. It’s especially useful for protecting the main or release branches.

• Require conversation resolution before merging

  GitHub allows you to enforce that all comments and requested changes in a pull request must be addressed before it is merged.

Step 5: Save the branch protection rule

Once you have configured your options, click on the Create button at the bottom of the form to save the branch protection rule. Your branch will now be protected according to the rules you’ve specified.

Enforcing branch protection in GitHub workflows

GitHub automatically enforces these rules during every pull request and merge attempt. Here are a few points to consider for ensuring smooth branch protection GitHub workflow:

• Define clear team roles: Make sure that team members understand their roles in the code review process. For instance, specify which team members are responsible for approving pull requests or resolving discussions.

• Configure CI pipelines: Integrate CI/CD (continuous integration/continuous deployment) pipelines with GitHub so that required checks run automatically. This can include running unit tests, security scans, and linters as part of your branch protection rules.

• Regularly audit branch protection settings: Review your branch protection settings periodically to check that they still meet your project’s needs. For example, you might want to increase the number of required reviews as your team grows or add new CI checks.

• Use GitHub Actions for additional automation: GitHub Actions can further automate the enforcement of your branch protection rules. For example, you can set up actions to notify team members when a pull request is ready for review or automatically assign reviewers.

Graphite Protections: another option for branch protection rules

For teams looking for more granular control over PR merges, Graphite Protections offers an advanced alternative to GitHub branch protection rules. Unlike GitHub’s blanket policies for entire repositories, Graphite Protections allow you to enforce mergeability requirements at the individual PR level based on factors like file path, programming language, team, and more. Plus, Graphite Protections integrates smoothly with GitHub Branch Protection Rules and CODEOWNERS, allowing you to adopt this powerful tool gradually.

Takeaways

By enforcing branch protection in GitHub, you'll establish a consistent and secure workflow that protects your codebase from unintended changes. GitHub’s branch protection rules provide fine-grained control over how and when changes are merged into critical branches to ensure stability and reliability. For teams looking for even more flexibility, Graphite Protections offer an advanced alternative, allowing mergeability requirements to be tailored to individual PRs based on factors like file path, team, or language. This added control, especially useful in monorepos, enhances compliance without slowing down development. Whether using GitHub’s branch protection rules or Graphite Protections, your team will experience improved code quality, collaboration, and confidence in the workflow.