Using branch permissions

Still need help?

The Atlassian Community is here for you.

Ask the community

Branch permissions allow you to control the actions users can perform on a single branch, branch type, or branch pattern within a repository. Branch permissions provide another level of security within Bitbucket Server, along with user authentication and projectrepository and global permissions, that together allow you to control, or enforce, your own workflow or process.

Branch permissions:

  • are based on users or groups.
  • are actually restrictions, which are checked after project and repository level permissions.
  • are used to limit branch access to specific people, or services, that still need write access to the project or repository.
  • prevent unauthorized users pushing to or deleting the branch.
  • can be based on explicit branch names, branch pattern, branching model.
  • currently do not prevent branch creation. Branch permissions will only be enforced on updates to existing branches and tags.

For example, if two developers Xavier and Yves have write access to repository R, but only Xavier has branch permissions on branch B, then Yves won't be able to push to B.

If a user does not have commit access to the branch, an error message will be shown on the Git command line when they try to push a change to the branch. If no branch permissions are defined then anyone with commit access to the repository can push to any branch. 

Adding branch permissions

Branch permissions in Bitbucket Server control access to repository branches. You need either project admin, admin or sys-admin permission to set or modify branch permissions.

To add branch permissions:

  1. Go to a repository in a project.
  2. Choose Settings > Branch permissions.
  3. Click Add permission.
  4. In the Branches field, select either Branch name, Branch pattern, or Branching model.
    1. Branch name - select an existing branch by name.
    2. Branch pattern - specify a branch using branch pattern syntax for matching branch names. See Branch permission patterns for more information about this syntax.
    3. Branching model - select the branch type to restrict access to. Read more about branching models.  
  5. Select the type of actions you want to prevent.
    1. Prevent all changes - prevents pushes to the specified branch(es) and restricts creating new branches matching the specified branch(es) or pattern.
    2. Prevent deletion - prevents branch and tag deletion. See Branch permission patterns for information about specifying tags.
    3. Prevent rewriting history - prevents history rewrites on the specified branch(es) - for example by a force push or rebase.
    4. Prevent changes without a pull request - prevents pushing changes directly to the specified branch(es); changes are allowed only with a pull request.
  6. Optional: Add exemptions for any of the selected restrictions. Adding a user, group, or SSH access key as an exemption means that it will not apply to them. This is not required; not adding any exemptions means the restriction will apply to everyone.
  7. Click Create to finish.

You can always change the permissions for a branch later, if necessary.

Last modified on Feb 6, 2019

Was this helpful?

Provide feedback about this article

In this section

Powered by Confluence and Scroll Viewport.