Branch permissions

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

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.
  • Create permissions for a specific branch type, or pattern. For example: /PROJECT-* to limit access to all branches with names like PROJECT-1234.
  • Prevent users from force-pushing to a branch.
  • Prevent a branch from being deleted.

If you want even tighter control over your team's workflow, check out merge checks. Merge checks allow you to recommend or require specific conditions on merges for individual branches or branch patterns. Learn more about merge checks.

Merge checks are a Premium feature for Bitbucket Cloud. Learn more about Bitbucket Premium.

This page

Related pages

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, 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. By name 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. By name 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.

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

Differences with Mercurial branch management

For Mercurial repositories, branch management differs in that bookmarks are also supported. Similar to Git’s branch permissions, Bitbucket Cloud allows you to limit pushes for both bookmarks and named branches by setting branch permissions. Unlike in Git, you can’t allow the rewriting of branch history or the deletion of a branch via the Branch permissions settings, but you can prevent the deletion of a bookmark by adding the bookmark name to your Bookmark management settings.

If a user has write access to your Mercurial repository, you can't prevent history rewrites or rebasing.

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 master but also created a permission using the branch pattern *, then, for the master branch, both permissions would be applied.


This table shows examples of results of overlapping permission definitions:

Wildcard (*) branch patterns Specific ("master") branch name 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
Everybody Alana Only Alana has access
Alana Harvey Both Alana and Harvey have access
Alana No users or groups Only Alana has access
Alana Everybody Only Alana has access
Last modified on Mar 21, 2019

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.