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 who must still have 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, or branching model.

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. Branch deletion - prevents branch and tag deletion. See Branch permission patterns for information about specifying tags.
    2. Rewriting history - prevents history rewrites on the specified branch(es) - for example by a force push or rebase.
    3. Changes without a pull request - prevents pushing changes directly to the specified branch(es); changes are allowed only with a pull request.
    4. All modifications - prevents pushes to the specified branch(es) and restricts creating new branches matching the specified branch(es) or pattern.
  6. Optional: Add exemptions for any of the selected restrictions. Adding a user or group 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 May 26, 2016

Was this helpful?

Provide feedback about this article

In this section

Powered by Confluence and Scroll Viewport.