Set Up Branch and Merge Restrictions
While project roles give you the ability to manage write an read permissions in repositories, that alone may not be enough to ensure code quality and efficient collaboration.
Branch protection settings let you safeguard important branches from inadvertant actions and undesireble changes without imposing excessive restrictions on the entire repository.
By creating security rules for a specific branch, you can:
Prevent accidental branch deletion.
Restrict who can push or force push to the branch.
Restrict who can merge changes into the branch.
Enable Quality Gates to ensure that only successfully tested, reviewed and approved changes find their way into the branch.
For example, you can prohibit direct pushes to master and require that all changes be submitted via merge requests, pass certain automated checks and have enough approvals from a specified group of members before they can be merged into master.
To set up a branch protection rule:
Open the Repository Settings page.
Go to the Protected Branches tab.
Existing rules (if any) are listed on this page.
To edit an existing rule, click next to it.
To create a new rule, click New rule.
Refer to the descriptions below to configure the restrictions and press Save when done.
Specify the branches
Specify branches which should be affected by restrictions in this rule. You can add one specific branch, several branches at a time, all branches, or any branch that matches a naming pattern. Use the following syntax:
+:<branch name>to include a branch (e.g.
-:<branch name>to exclude a branch (e.g.
*as a wildcard. For example,
+:*will include all branches.
To specify branches which names contain a specific string, enclose that string in asterisks. For example, to include all branches containing
prod-1, etc.), enter:
Specify members, roles, or applications that should be allowed to perform the following actions:
Create a new branch (from the protected branches specified in this rule).
Push to the protected branches.
Force push to the protected branches.
Delete the protected branches.
If you're going to enable the Quality Gates (described below) and require committers to submit their changes via merge requests, remove All committers from the Push and Force push fields and add only those who are allowed to bipass the restrictions.
Quality Gates for Merge Requests
To ensure that only verified and approved commits are merged into a protected branch, you can set up a number of requirments and conditions that should be met before merging.
With the quality gates enabled, a committer should first push their changes to another branch and create a merge request for their commit, specifying the protected branch as a target. The commit can be merged only if and when it satisfies the quality gates requirements specified here — e.g. after it passes selected automated checks it triggered and/or gets sufficient number of approvals from specified members.
Turn the switch On to configure and enable these settings.
Members Required to Pass Quality Gates
Specify members who will be allowed to execute a merge into a protected branch once all conditions are met. If you add a role (e.g. Project Admin), all members which have that role will get the right to merge.
Make sure you have the Push and Force push actions restricted in the Regulated Actions section above. Otherwise, all project members will be able to push directly to the protected branch, bypassing the quality gates conditions.
Allow to merge changes only if they are reviewed and approved by specified members.
Require approval from code owners: changes made to the files owned by specific members will have to be approved by these members to allow the merge. File ownership should be defined in the CODEOWNERS file in advance. For information on how to set up the CODEOWNERS file, please read Code Owners.
Choose members whose approval is required and specify how many out of the selected members must approve the changes to allow the merge (e.g. any 2 members out of 5 selected).
If you have any Automation jobs set up to run on commits in your repository, they will be listed here. You can select all or any of them as a quality gates condition.
All selected jobs, if triggered by the commit, must complete successfully to pass the gates.
If your repository receives build statues from an external CI service (such as TeamCity, Jenkins), you can require one or more status checks to pass on a commit before allowing it to be merged.
Each service connected to your repository will be listed here along with the checks they run. Select services that must comlete successfully to pass the quality gates.
Example of a protected branch configuration
Let's consider a common scenario where your repository has a lot of contributors and a master branch reserved for production. To keep the master branch healthy, you don't want any changes pushed to it, unless they are reviewed and approved by at least one experienced developer. Since you have Space automation set up to run test jobs on commits, you also want all commits to pass automated status checks before they can be submitted to master.
Here is how you should configure your branch protecton settings:
Open the Repository Settings page and go to the Protected Branches tab:
Click New rule to open the form.
Specify master as your protected branch.
Allow no one to Push and Force push to master, but allow all commiters to create new branches from master.
You obviously don't want master accidentally deleted, hence allow this action to no one.
Turn on the Quality Gates settings.
You want to allow every committer to merge changes to master after they pass all the requirements:
You don't want any changes merged unless they've been reviewed and approved by at least one of these three members:
At last, you want all commits to successfully pass automated checks before they can be merged to master, so you select the jobs listed here as a requirement:
Don't forget to Save your configuration. You can always view and edit it on the Repository Settings page under the Protected Branches tab: