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

1. Select Projects on the top navigation bar to access the projects within the workspace.

2. Select the project in which you want to add branch restrictions.

3. Select Project Settings on the left navigation sidebar.

4. Select Branch restrictions on the left navigation sidebar.

5. 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)

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:

Suggest or require checks before a merge

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

If you're on our Premium plan, you also have access to the following settings.