Branch permissions are a great way to balance giving your team the freedom to get work done while enforcing workflows and preventing unwanted changes or deletions being made to your codebase. Bitbucket Cloud makes it easy to control which users and groups can write to or merge a branch, prevent users from force-pushing or deleting a branch, and lets you create permissions for a specific branch type or pattern too.
Setting up branch permissions
Branch permissions are set on a per-repository basis by specifying a user or group who already has access to a given repository. Restrictions are based on explicit branch names, or you can use advanced branch permissions to match multiple branches using branch patterns.
To add branch permissions to a repository:
1- Navigate to a repository in a project.
2- Choose Settings > Branch permissions.
3- Click Add a branch permission.
4- In the Select branch field, select either By name or pattern or By type.
5- In the Write access field, add the users and/or groups who can push or merge changes to the branch. (By default users do not have permission to rewrite branch history and/or delete the branch, but you can allow for these by checking each individual check box.)
6- In the Merge via pull request field, add the users and/or groups who can merge to this branch via a pull request.
7- Merge checks allow you to recommend or require specific conditions on merges for individual branches or branch patterns. You can use merge checks to recommend or require the following conditions before a merge:
| Setting | Result |
|---|---|
| Check for at least {#} approvals | Users get notified when pull requests don’t have that number of approvals. |
| Check for unresolved pull request tasks | Users get notified when they have open pull request tasks. |
| Check for {#} passed builds on the last commit | Users get notified when they don’t have that number of successful builds for the most recent commit. |
| Prevent a merge with unresolved merge checks (PREMIUM PLAN) | Users won’t be able to merge if their pull request has unresolved merge checks. They’ll see a checklist of what they need to resolve so that they can complete the merge. |
| Reset approvals when the source branch is modified (PREMIUM PLAN) | If there are any changes to the source branch of the pull request, the pull request updates with no approvals, and the reviewers have to review and approve the pull request again. |
Automatically add permissions when creating branches
For teams with standardized naming schemes for their branches you can automatically set branch permissions whenever a branch is created by utilizing branching models. Branching models make it easier to maintain consistent naming conventions when creating branches and, when used in conjunction with branch permissions, results in the same permissions applied to every branch created of a certain type.
To set branch permissions for your branching model, simply select the By type option in the Select branch field when adding a branch permission.
Take control with branch permissions today
Branch permissions are a great way to protect critical branches and when used alongside your branching model, provide a robust and automated way to enforce your workflow with minimal overhead. Set up your branch permissions today and let us know what you think!
Looking to enforce merge checks? Learn how to upgrade your plan