Protecting Your Main Branch in Bitbucket Cloud: A Practical Guide to Branch Permissions

Problem: Uncontrolled Direct Pushes Hinder Code Quality

In many teams, developers push directly to the main branch out of habit or convenience. A single accidental commit can break CI, introduce bugs, or create merge conflicts that waste time. The root cause is the lack of a gate that forces code review and automated testing before changes reach the critical branch.

Thesis: Use Bitbucket Cloud’s Branch Permissions to Enforce Review, Build, and Safety Gates

Branch Permissions provide a declarative way to lock branches such as main or release/*. By requiring pull‑request approvals, successful builds, and preventing force pushes, you can guarantee that every change is vetted and validated. The feature is available on all paid plans and even the free tier for small teams, making it an accessible engineering decision for most projects.

1. What Are Branch Permissions?

Branch Permissions let you define rules that apply to a specific branch or a branch pattern. The supported controls include:

• Require pull‑request approvals: No direct push is allowed; all changes must go through a PR and receive the required number of approvals.
• Require successful builds: A Bitbucket Pipelines build must finish green before a merge can be completed.
• Prevent force pushes: Even admins cannot rewrite history on the protected branch.
• Restrict who can merge or delete the branch.

Once a rule is in place, it automatically applies to every future commit, so the protection is persistent without further configuration.

2. Configuring a Protected Main Branch via the UI

Follow these steps to lock main:

1. Navigate to Repository Settings → Branches → Branch Permissions in the Bitbucket web UI.
2. Click Add permission rule.
3. Set Branch name pattern to main.
4. Enable Require pull‑request approvals and set the number of required approvals (e.g., 2).
5. Enable Require successful build and choose the pipeline that should run.
6. Check Prevent force pushes.
7. Optionally, specify users or groups who can merge or delete the branch.
8. Save the rule.

After saving, any attempt to push directly to main from a non‑approved user will be rejected with a clear error message in the UI and the API.

3. Automating Permissions with the REST API

For teams that manage many repositories or want to enforce policies consistently, the REST API is handy. Below is a minimal example that creates the same rule on a given repository. Replace placeholders with your actual values.

curl -X POST \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Protect main branch",
    "branch": "main",
    "restrictions": [
      {
        "type": "push",
        "kind": "deny",
        "users": [],
        "groups": []
      },
      {
        "type": "force",
        "kind": "deny",
        "users": [],
        "groups": []
      }
    ],
    "pullRequest": {
      "minApprovals": 2,
      "build": {
        "enabled": true,
        "pipeline": "default"
      }
    }
  }' \
  "https://api.bitbucket.org/2.0/repositories/<workspace>/<repo-slug>/branch-restrictions"

After the request succeeds, the rule is active. Verify by attempting a direct push from a user that is not part of the allowed groups; the push should fail.

4. Trade‑offs and Limitations

• Speed vs. Safety: Developers may find the extra steps (creating a PR, waiting for CI) slower during rapid prototyping. Mitigate by using feature branches and only protecting critical branches.
• Admin Override: Users with the admin permission can still bypass some restrictions. Keep admin rights to a minimum and use group-based restrictions where possible.
• Naming Conventions: Branch Permissions do not enforce naming patterns. Combine them with branch naming policies or pre‑push hooks if you need strict naming rules.
• Pipeline Integration: The “require successful build” rule relies on Bitbucket Pipelines. If your CI runs elsewhere, you must trigger a status check that Bitbucket can consume.

5. Actionable Checklist

1. Identify critical branches (e.g., main, release/*). Decision point: Do you need to protect all of them or only the most stable ones?
2. Define the desired policy: number of approvals, required CI, force‑push prevention.
3. Implement the rule via the UI for quick testing.
4. Automate the rule with the REST API if you manage multiple repos.
5. Communicate the new workflow to the team and provide a quick guide on creating PRs.
6. Monitor the first few weeks: check for rejected pushes, build failures, and user feedback.
7. Adjust the policy if it hampers productivity—e.g., lower the approval count or allow certain trusted developers to push directly.

By following this approach, you lock down your main branch, enforce code review, and maintain a healthy CI pipeline—all while keeping the process transparent and auditable.