Get started with Bitbucket Cloud
New to Bitbucket Cloud? Check out our get started guides for new users.
Configure a project's branch restrictions
Project branch restrictions are a way for an admin to set branch permissions and merge settings across all the repositories within a project. Note: Project branch restrictions are no different than repository branch restrictions when it comes to enforcement and administration.
As an admin, you may want to set branch restrictions within a project to create a consistent set of branch permissions and merge checks across all the repositories within the project, meaning all the branch restrictions set within a project are enforced on every repository within that project so you don’t have to set branch restrictions per repository.
Access and add project branch restrictions
Select Projects on the top navigation bar to access the projects within the workspace.
Select the project in which you want to add branch restrictions.
Select Project Settings on the left navigation sidebar.
Select Branch restrictions on the left navigation sidebar.
Select Add a branch restriction.
See the sections below for more specifics on using branch permissions, including branch types and branch patterns, and setting merge checks.
Use branch permissions
Branch permissions help enforce specific workflows and prevent errors like a new workspace member deleting the main branch.
With branch restrictions 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.
Rules for branch permission priority (condensed version of what gets enforced)
User and group access overrides anything else (ALLOW vs DENY is unspecified, since existing code only uses ALLOW here)
DENY overrides ALLOW
Anything can override non-branch specific access
Highest extra value wins if there's a conflict (should never interfere with other rules)
If you want even tighter control over your workspace'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.
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
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 main but also created a permission using the branch pattern *, then both permissions (main & *) would be applied to the main branch.
This table shows examples of results of overlapping permission definitions:
Wildcard (*) branch patterns | Specific ("main") 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 |
Suggest or require checks before a merge
Bitbucket Premium
Providing your users with recommended checks to consider before merging is available to everyone. However, we also offer a few Premium merge checks:
Enforce merge checks to ensure every pull request is fully vetted before it gets merged.
Require another approval from reviewers, if the source branch of a pull request is modified.
Keep approvals if there are no changes to the files
Merge checks allow you to recommend or require specific conditions on merges for individual branches or branch patterns. Merge checks work in tandem with branch permissions to give the members of your workspace flexibility and control over your development workflow.
Purpose of merge checks
Dependent merges
Ensure users are only merging changes with passing builds.
Select a specific number of successful builds before a merge.
Use with Bitbucket Pipelines, a build tool integration, or our commit status REST API.
Code review completion
Tie merges to code review.
Get your colleagues working collaboratively with pull requests.
Keep your workflow consistent so developers know what they have to do to merge.
Task completion
Create tasks on pull requests to mark changes that need to be made.
Manage a pull request as it progresses to approval.
Ensure all tasks in a pull request are complete before a merge.
Merge checks
You can use merge checks to recommend or require the following conditions before a merge.
When you select any of these options (and don't have the Premium plan), we'll warn users when they have unresolved merge checks, but they'll still be able to merge. To prevent users from merging, upgrade to Premium and select Prevent a merge with unresolved merge checks. Learn more about Premium
Setting | Result |
|---|---|
Minimum number of approvals | Users get notified when pull requests don't have that number of approvals. |
Minimum number of approvals from default reviewers | Users get notified when pull requests don't have that number of approvals from default reviewers. |
No changes are requested | Users get notified if pull requests have ‘Changes requested’ associated with any of the reviewers. |
No unresolved pull request tasks | Users get notified when they have open pull request tasks. |
Minimum number of successful build for the last commit with no failed builds | Users get notified when they don't have that number of successful builds for the most recent commit. |
Reset requested changes when the source branch is modified | Automatically resets any ‘Changes requested’ statuses when the source branch is modified. |
Allow automatic merge when builds pass | The PR author or an admin can enable this feature to queue up a pending merge to be triggered automatically once all the merge checks have passed. |
If you're on our Premium plan, you also have access to the following settings.
Setting | Result |
|---|---|
Reset approvals when the source branch is modified | 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. |
Keep approvals if there are no changes to the files | Ensures that any approvals that were made are kept intact if there are no changes to the files. |
Prevent a merge with unresolved merge checks | 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 before the merge can be executed. |
Branch permissions & merge settings examples
For more information and examples, refer to our branch permissions and merge settings support documents:
Project permissions
Looking to provide project access and permissions to users or a group? Refer to our Configure project permissions to users and groups help document.
Was this helpful?
Still need help?
The Atlassian Community is here for you.