Using branch permissions
Branch permissions in Bitbucket Server control access to repository branches. This page describes branch permissions, and how to add branch permissions for an entire project or a single repository.
About branch permissions
On this page:
Branch permissions provide another level of security in Bitbucket Server, with user authentication and project, repository and global permissions, that together allow you to control or enforce your own workflow or process. With branch permissions you can control the actions users can perform on a single branch, branch type, or branch pattern within a repository or project.
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
Good to know:
- Branch permissions are based on users or groups, and are actually restrictions, which are checked after project and repository level permissions, and prevent unauthorized pushing to or deleting a branch.
- They do not prevent branch creation. Branch permissions will only be enforced on updates to existing branches and tags.
You can add branch permissions for all repositories in a project, or for individual repositories. Also, you can add multiple branch permissions for a project or repository. When creating a branch permission, you need to specify how to apply the permission, by either branch name, branch pattern, or branching model. You can also create exceptions for specific users, groups, or access key when creating or editing branch permissions.
Add branch permissions for all repositories in a project
To add branch permissions for all repositories in a project (requires project admin permission):
- Go to Project settings > Branch permissions.
- Click Add permission.
- In the Branches field, specify which branches the permission applies to, either by Branch name, Branch pattern, or Branching model.
In the Restrictions field, select the type of actions to prevent and add exemptions for any of the selected restrictions.
Adding a user, group, or access key as an exemption means that restriction will not apply to them.Not adding any exemptions means the restriction will apply to everyone.
Click Create to finish.
'Add a branch permission' dialog for a project
There are several ways to configure your branch permissions scheme when adding branch permissions for your project or repository. The section above outlines how to add branch permissions, however this section outlines the various options that are available from the Add a branch permission dialog.
'Branches' field options
For each branch permission, first determine which branch (or branches) to apply the permission to by either selecting a branch by name, branch pattern, or branching model.
Branch name
Enter the name of an existing branch to apply to restrict access to. Used to restrict access to a single branch.
Branch pattern
Use branch pattern syntax to select matching brances. Read more about Branch permission patterns.
Branching model
Select a branch type to restrict access to multiple branches. Read more about branching models.
'Restrictions' field options
Once you determine which branches a permission applies to, you then determine which actions to prevent, and optionally set exceptions to this permission.
Prevent all changes
Prevents pushes to the specified branch(es) and restricts creating new branches that match the branch(es) or pattern.
Prevent deletion
Prevents branch and tag deletion. Read Branch permission patterns for information about specifying tags.
Prevent rewriting history
Prevents history rewrites on the specified branch(es) - for example by a force push or rebase.
Prevent changes without a pull request
Prevents pushing changes directly to the specified branch(es); changes are allowed only with a pull request.
Add branch permissions for a single repository
Adding branch permissions for an individual repository creates an additional branch permission. This means that the repository will have branch permissions from the project settings, and any additional branch permissions specifically set for a repository.
To add branch permissions for a single repository (requires repo admin permission):
- Go to Repository settings > Branch permissions.
- Click Add permission.
- In the Branches field, specify which branches the permission applies to, either by Branch name, Branch pattern, or Branching model.
In the Restrictions field, select the type of actions to prevent and add exemptions for any of the selected restrictions.
Adding a user, group, or access key as an exemption means that restriction will not apply to them.Not adding any exemptions means the restriction will apply to everyone.
Click Create to finish.
'Add a branch permission' dialog for a repository
There are several ways to configure your branch permissions scheme when adding branch permissions for your project or repository. The section above outlines how to add branch permissions, however this section outlines the various options that are available from the Add a branch permission dialog.
'Branches' field options
For each branch permission, first determine which branch (or branches) to apply the permission to by either selecting a branch by name, branch pattern, or branching model.
Branch name
Enter the name of an existing branch to apply to restrict access to. Used to restrict access to a single branch.
Branch pattern
Use branch pattern syntax to select matching brances. Read more about Branch permission patterns.
Branching model
Select a branch type to restrict access to multiple branches. Read more about branching models.
'Restrictions' field options
Once you determine which branches a permission applies to, you then determine which actions to prevent, and optionally set exceptions to this permission.
Prevent all changes
Prevents pushes to the specified branch(es) and restricts creating new branches that match the branch(es) or pattern.
Prevent deletion
Prevents branch and tag deletion. Read Branch permission patterns for information about specifying tags.
Prevent rewriting history
Prevents history rewrites on the specified branch(es) - for example by a force push or rebase.
Prevent changes without a pull request
Prevents pushing changes directly to the specified branch(es); changes are allowed only with a pull request.