Use branch permissions

Branch permissions help enforce specific workflows and prevent errors like a new workspace member deleting the main branch.

With branch permissions you can:

• Closely control which users or groups can write or merge to any branch.

• Create permissions for a specific branch type, or pattern. For example: PROJECT-* to limit access to all branches with names like PROJECT-1234.

Rules for branch permission priority (condensed version of what gets enforced)

• User and group access overrides anything else (ALLOW vs DENY is unspecified, since existing code only uses ALLOW here)

• DENY overrides ALLOW

• Anything can override non-branch specific access

• Highest extra value wins if there's a conflict (should never interfere with other rules)

Example permissions set up

So, let's say Alana (Principal Engineer), Harvey (QA lead), and another 5 engineers are working on a Teams in Space project. You want everyone to be able to do work effectively so everyone has write access to the repository. Now you need to manage access to the repositories main and develop branches. You might want to assign permissions like this: 

• Allow only Alana to write directly to main.

• Allow only Alana and Harvey to merge into main.

• Allow everyone to merge to develop but only through a pull request.

Below are the steps describing how to set up this example

Start by navigating to the repository you want to limit permissions for, select Repository settings, then select Branch restrictions.

Add permissions to Main branch:

1. Select Add a branch restriction.

2. Enter the following into each field, then select Save:

   1. By name or pattern: Main

   2. On the Branch permissions tab under Write access, select Only specific people or groups have write access: Alana Persona

   3. On the Branch permissions tab under Merge access via pull requests, select Only specific people or groups have merge access: Harvey Persona

Now add permissions for the Develop branch:

1. Select Add a branch restriction.

2. Enter the following into each field, then select Save.

   1. By name or pattern: Develop

   2. On the Branch permissions tab under Write access, select Only specific people or groups have write access: Alana Persona and Harvey Persona (Alana and Harvey also get merge via pull request permissions).

   3. On the Branch permissions tab under Merge access via pull requests, select Only specific people or groups have merge access: Developers

Branch types

If you've got the branching model enabled, you can configure permissions for all branches of a specific type. This might be useful if you want to restrict merge access on all release branches, for example.

Branch patterns

If you need to get more granular than type, you can also set permissions for a specific pattern of branch name like PROJECT- by adding a wild card character (*) to either end of the string. For example:

PROJECT-* Matches branch named PROJECT-*, even in a name space, so restrictions would apply to the following branches:

• PROJECT-1234

• PROJECT-new

• PROJECT-1.1

Branch permissions overlap

It's possible to accidentally overlap your branch permissions. For example, if you created a branch permission specifically for the branch name main but also created a permission using the branch pattern *, then both permissions (main & *) would be applied to the main branch.

This table shows examples of results of overlapping permission definitions: