Enforcing Protected Branches with Bitbucket Branch Permissions

Preventing Direct Pushes to Production Branches

Unrestricted access to a primary branch—such as main or master—increases the risk of unstable code reaching production, accidental deletions, or bypassing the peer review process. The solution is to implement Branch Permissions, which decouple the ability to write code from the ability to merge it into a protected branch.

The primary takeaway is that by disabling direct pushes and requiring Pull Requests (PRs), you shift the governance of the codebase from individual trust to a documented, review‑based workflow.

Prerequisites

• Administrative Access: You must have Repository Administrator permissions for the target repository.
• Defined Branching Strategy: A clear understanding of which branches are "protected" (e.g., main, develop) and which are "feature" branches.
• User Groups: Pre‑defined Bitbucket groups (e.g., lead-engineers or release-managers) if you intend to grant specific bypass privileges.

Configuring Branch Restrictions

Follow these steps to lock down a production branch. These instructions apply to Bitbucket Cloud and Data Center versions, though menu labels may vary slightly between versions.

1. Navigate to the Repository settings in the left-hand sidebar.
2. Under the Workflow section, select Branch permissions.
3. Click Add permission.
4. Select Branch: Choose the specific branch (e.g., main) or use a pattern for multiple branches (e.g., release/* to protect all release versions).
5. Restrict Write Access: Uncheck the box for "Allow all users to push" or explicitly define the users/groups who are permitted to push. To enforce a PR‑only workflow, ensure no general developers are listed here.
6. Enforce Pull Requests: Enable the setting Prevent changes without a pull request. This ensures that even users with write access cannot push directly; they must use the PR interface.
7. Merge Checks: (Optional) Configure requirements such as "Minimum number of approvals" to ensure at least one or two peers have signed off on the code.
8. Click Save.

Implementation Example: The 'Release' Pattern

In many engineering teams, protecting only main is insufficient because release branches also require stability. Instead of creating a rule for every version, use a wildcard pattern.

Pattern	Target Branches	Intended Restriction
main	Main production branch	No direct pushes; 2+ approvals required.
release/*	release/1.0, release/2.1, etc.	Only release-managers group can push/merge.
feature/*	All feature branches	No restrictions (allows rapid iteration).

Verification and Diagnostics

To ensure the permissions are active and correctly configured, perform the following checks using a non‑administrator account.

1. Test Direct Push Rejection

Run the following command from a local terminal using a developer account that should be restricted:

git checkout main
git commit -m 'Test unauthorized push'
git push origin main

Expected Result: The push should be rejected by the remote server with an error message similar to pre-receive hook declined or you are not allowed to push to this branch.

2. Verify PR Workflow

Create a feature branch, push a change, and open a Pull Request targeting main.

• Check if the Merge button is disabled.
• Verify that the button only becomes active once the required number of approvals is met.

Recovery and Emergency Access

Overly restrictive permissions can block critical hotfixes during a production outage. To resolve a lockout:

• Temporary Bypass: An administrator can temporarily add the emergency responder to the "Allowed to push" list in Branch Permissions.
• Rollback: To remove all restrictions, navigate back to Branch permissions and delete the specific rule associated with the branch. This immediately restores default Git behavior where anyone with write access to the repo can push to any branch.

Limitations

Note that repository administrators may still have the ability to bypass certain restrictions depending on the global workspace settings. Additionally, branch permissions do not prevent the deletion of the repository itself; they only protect the internal branch structure.