Branch permissions

Branch permissions help enforce specific workflows and prevent errors like a new team member deleting master.

With branch permissions you can:

  • Closely control which users or groups can write or merge to any branch.
  • Crete permissions for a specific branch pattern like /PROJECT-* to limit access to all branches with names like PROJECT-1234.

 

 

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 master and develop branches.  You might want to assign permissions like this: 

  • Allow only Alana to write directly to master.
  • Allow only Alana and Harvey to merge into master.
  • Allow everyone to merge to develop but only through a pull request.
  Click here to see how to set up this example

Start by navigating to the repository you want to limit permissions for and click Settings then click Branch permissions.

Add permissions to Master branch:

  1. Click Add a branch permission.
  2. Enter the following into each field, then click Save:
    1. Branch or pattern: master
    2. Write access: Alana Persona
    3. Merge via pull request: Harvey Persona

Now add permissions for the Develop branch:

  1. Click Add a branch permission.
  2. Enter the following into each field, then click Save.
    1. Branch or pattern: Develop
    2. Write access: Alana Persona and Harvey Persona (Alana and Harvey also get merge via pull request permissions).
    3. Merge via pull request: Developers


The result will look something like this:

You can also see that no one can either delete or rewrite history on either branch.

If you want even tighter control over your team's workflow, check out merge checks. Merge checks are a Premium feature for Bitbucket Cloud, but you can try them free for a limited time!

Learn more about Bitbucket Premium.

Branch patterns

You can 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 and branch or tag named PROJECT-*, even in a name space, so restrictions would apply to the following branches:

  • PROJECT-1234
  • PROJECT-new
  • PROJECT-1.1

Understand the differences with Mercurial branch management

Unlike Git's single branch concept, Mercurial supports both bookmarks or named branches.  For Mercurial repositories, support for branch management is slightly different. Bitbucket Cloud allows you to limit pushes for both bookmarks and named branches.  You can only prevent the deletion of bookmarks; you cannot prevent deletion of named branches.

You cannot prevent history re-writes or rebasing in a Mercurial repository.

Branch permissions overlap

Branch permissions overlap usually happens:

  • When you create a branch pattern which matches an existing branch but has different permissions.
  • When you create a branch with different permissions which also matches an existing branch pattern with permissions.

For example creating the branch develop then creating a branch pattern develop* will cause overlapping permissions.

What this means is permissions from both the branch and the branch pattern are applied.

Wildcard (*) branch patterns Specific ("master") branch pattern What's enforced for branches included in both restrictions
User or group restrictions (write or merge access)
No users or groups listed Alana Only Alana has access
All users or groups Alana Only Alana has access
Alana Harvey Both Alana and Harvey have access
Alana No users or groups Only Alana has access
Alana All users or groups Only Alana has access

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport