How to Setup Branch Protection Rules

user profile
Backend Engineer

Introduction

Branching is the cornerstone of cooperative work using Git. Developers utilize branches to work on the same source code repository in parallel. Generally speaking, when working with branches, there is one main branch in a repository from which various developers create their own additional, diverging branches. Once a developer’s project is done, they then merge their side branch back into the main branch.

The ability to create and later merge branches introduces a risk, however: Developers may inadvertently push insecure content into the Git repository’s main branch.  In order to minimize risk, source code management platforms introduced branch protection rules. Let’s deep-dive into what the major platforms offer.

GitHub

GitHub introduced the most elaborate branch protection options to date, which you can access via your repository’s Settings section, under Branches.

If you don’t already have rules in place, then simply click on the Add rule button to begin.

This will reveal the following options:

Branch name pattern

This field is dedicated to specifying the branch(es) for which these rules will apply. It supports regular expressions. If you only want these rules to apply to one branch, simply write that branch’s name.

Protect matching branches

This section allows you to enable several protections:

Require pull request reviews before merging: It is best practice to prohibit pushing unreviewed content to the main branch. Such a restriction greatly reduces the risk of a developer accidentally pushing sensitive content such as private keys or passwords. At least one reviewer should be set. Perform reviews when new content is added in order to ensure all pushed content is validated. If a CODEOWNERS file exists in your repository, you should only allow code owners to review code changes.

Require status checks to pass before merging: Even though code reviews are done by a team leader or a colleague, mistakes could happen, which is why we recommend implementing automatic status checks that validate that no sensitive content was added.

Note: Cycode offers an automatic secret scan which will instantly alert the developer in the event that sensitive content has been added to the repository.

Require signed commits: Github allows commits to be signed using GPG or S/MIME. We recommend utilizing signatures to ensure the content submitted by the developer was not altered part of an attack.

Require linear history: This setting helps with tracking changes in the main branch and will require developers only use a squash merge or rebase merge when merging the side branch into the main one.

Include administrators: We encourage enforcing these restrictions on administrators as well; just remember that administrators can change these settings.

Restrict who can push to matching branches: We recommend only granting write permission to users who specifically need to write content to the repository. If you wish to restrict specific users, teams or apps from pushing content, you can utilize the settings under this section accordingly.

Rules applied to everyone, including administrators

This section is critical as it revolves around some basic Git actions that are extremely dangerous if performed irresponsibly.

Allow force pushes: The ability to force pushes, legitimate use cases notwithstanding, essentially allows developers to Git boundaries and make changes that are sometimes irreversible. It is simply smarter and safer to disallow force pushes and not undertake the risk. If one must perform a force push, then we advise doing so only under supervision and with extreme caution. In such a scenario, this restriction can be lifted prior to force-pushing content, then restored immediately afterward.

Allow deletions: This setting allows developers to delete protected branches. We of course advise against allowing anyone to delete a protected branch.

Bitbucket

Bitbucket refers to their branch protection rules as “branch permissions” that govern which users are allowed to make changes to a protected branch. To access these settings, navigate to Repository settings, then to Branch permissions.

If this is the first time configuring these settings, click the Add a branch permission button.

The following settings appear:

Select branch: Configure the relevant protected branch by entering the branch’s name, or if you wish to select multiple branches, enter the corresponding pattern or type.

Write access: Meticulously define a specific developer group to be able to merge changes to the protected branch.

Merge checks: Define at least 1 approval before merging. Having another person review the changes is critical to prevent human errors from happening.

GitLab

GitLab allows you to protect specific branches under the Protected branches section. First, navigate to your project’s Settings page (not to be confused with your user’s Settings page).

Next, click the Expand button to the right of Protected Branches.

You will then see the following settings:

GitLab

Branch: Select the branch to protect, either by providing its name or by using a pattern with a wildcard.

Allowed to merge: We recommend only allowing team leaders to merge content into the protected branch.

Allowed to push: We recommend prohibiting anyone from pushing content directly into the protected branch.

Require approval from code owners: If your repository maintains a CODEOWNERS file, we recommend that only the respective code owners allow changes to this repository.