Enforcing Code Reviews with Bitbucket Branch Permissions

The Problem: Unprotected Mainline Branches

When a repository allows direct pushes to a mainline branch (like main or master), the risk of introducing breaking changes, bypassing tests, or accidentally deleting history increases. To ensure stability, teams need a mechanism to mandate that all code enters the protected branch only after a peer review and successful CI (Continuous Integration) build.

Decision Framework: When to Enable Permissions

Implementing branch permissions introduces friction into the development loop. Before enabling them, evaluate these constraints:

• Workflow Dependency: Does your team have a defined Pull Request (PR) process? If not, blocking direct pushes will halt all deployments.
• Automation Impact: Do you have legacy CI/CD scripts or bots that push version tags or documentation updates directly to the protected branch? These will fail upon activation.
• Plan Limitations: Are you on a Bitbucket Cloud Free plan? Some advanced restrictions, such as blocking force-pushes or requiring specific approval counts, require a paid subscription.

Comparison of Permission Options

Feature	Bitbucket Cloud (Free)	Bitbucket Cloud (Standard/Premium)	Bitbucket Server/Data Center
Direct Push Block	Supported	Supported	Supported
Pattern Matching	Basic (e.g., release/*)	Advanced Patterns	Advanced Patterns
Force Push Block	Limited	Full Control	Full Control
Merge Checks	Basic	Required Approvals/Builds	Customizable Merge Checks

Trade-offs and Risks

• Velocity vs. Stability: Requiring a review for every single commit can slow down small teams. Consider using branch patterns (e.g., feature/*) to keep development fast while locking down main.
• Administrative Overhead: Permissions are configured at the repository level. In large organizations, failing to standardize these settings across all repositories can lead to inconsistent enforcement.
• The "Admin Bypass": Repository administrators often bypass these rules by default. To truly test the workflow, validation must be performed with a non-admin account.

Implementation: Locking the Main Branch

This configuration ensures that no user can push directly to main and that every change requires at least one approval and a passing build.

1. Access Settings: Navigate to Repository settings → Branch permissions.
2. Create Rule: Click Add permission.
3. Configure Scope:
   • Branch name: Select main (or use a pattern like release/*).
   • Write access: Leave empty or assign only to a specific release-manager group to block all other direct pushes.
   • Merge checks: Check Require at least 1 approval and Require a successful build.
   • Restrictions: Check Prevent deletion and Prevent rewriting history (force push).
4. Save: Apply the changes to the repository.

Automated Configuration via REST API

For teams managing multiple repositories, use the Bitbucket Cloud API. Run this command from a terminal with curl installed. You will need an App Password with repository:admin permissions.

# Replace {workspace} and {repo_slug} with your actual identifiers
curl -X POST https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/branch-restrictions \n  -u username:app_password \n  -H "Content-Type: application/json" \n  -d '{
    "kind": "push",
    "pattern": "main",
    "users": [],
    "groups": []
  }'

Risk: Running this API call without specifying users or groups effectively blocks everyone (except admins) from pushing to that branch.

Verification and Validation

To confirm the permissions are active, perform these checks using a non-administrator account:

1. Test Direct Push: Attempt to push a local commit directly to the protected branch:

   git checkout main
   git commit -am "Testing permission block"
   git push origin main

   Expected Result: The push should be rejected with a 403 Forbidden or a message stating that the user does not have permission to push to this branch.

2. Test PR Workflow: Create a feature branch, push it, and open a Pull Request to main. Attempt to merge it before it is approved.

   Expected Result: The "Merge" button should be disabled or a warning should appear stating that merge checks (approvals/builds) have not been met.

Limitations and Rollback

Limitations: Branch permissions are not retroactive. If a branch was created after the rule was set but does not match the pattern, it will not be protected. Always verify that your patterns (e.g., main vs master) match your actual branch names.

Rollback: If a critical hotfix is blocked and the PR process is too slow, an administrator can navigate back to Branch permissions, select the rule, and either delete it or add the specific user to the Write access list to allow a temporary direct push.