What are branch permissions in Bitbucket and how do you protect the main branch?

Branch permissions are like velvet ropes at a nightclub. Everyone can see the VIP section (the main branch), but only authorized people (senior developers) can enter through the proper process (pull requests with approvals), and no one can just walk in through the back door (direct push).

Branch permissions in Bitbucket allow repository administrators to define rules for specific branches or branch patterns. You can restrict three actions: who can write (push) to a branch, who can merge via pull request, and who can delete the branch. These permissions are configured in Repository Settings > Branch Permissions. You can target specific branches (like 'main') or use glob patterns (like 'release/*') to cover multiple branches at once. Permissions can be granted to specific users, groups, or nobody at all (effectively locking the branch).

The enforcement mechanism works at the Git server level. When a developer attempts to push directly to a protected branch, Bitbucket rejects the push with an error message explaining which permission rule blocked it. This is different from client-side hooks (which can be bypassed) because the server itself refuses the operation. For merge-via-pull-request restrictions, Bitbucket ensures that changes to the protected branch can only come through approved pull requests, never through direct pushes. Administrators and users with explicit bypass permissions can override these restrictions when necessary.

In production, a typical main branch protection setup includes: no direct pushes allowed (all changes via PR), minimum two approvals required, all merge checks passing (green pipeline, no unresolved tasks), and deletion blocked. Teams also protect release branches with similar rules. Some organizations go further by requiring specific reviewers for certain file paths: for example, changes to the infrastructure/ directory might require approval from a platform engineer. This is configured through merge checks rather than branch permissions directly.

A gotcha to watch for: branch permissions in Bitbucket Cloud are set per repository, but in Bitbucket Data Center, they can be set at the project level and inherited by all repositories in the project. If you are migrating between the two, you will need to reconfigure permissions. Also, users with admin access to the repository can bypass branch permissions unless explicitly excluded, which sometimes creates a false sense of security if admin access is granted too broadly.