Locking Down Your Mainline: How Bitbucket Branch Permissions Keep Code Clean

Problem: A Mainline that Keeps Breaking

In large teams, the main or release branch is the heart of the product. When developers push code directly to it, integration bugs, broken CI runs, and accidental overwrites become common. Manual checks—like code reviews or CI status checks—are error‑prone and slow the delivery pipeline.

Thesis: Use Bitbucket Branch Permissions as Policy‑as‑Code

Bitbucket’s Branch Permissions let you declare who can push, merge, or delete a branch, and under what conditions. By configuring these rules, you turn a chaotic workflow into a predictable, enforceable process that reduces merge drift, protects the mainline, and speeds up release cycles.

Section 1 – What Branch Permissions Offer

• Pattern‑based rules: Apply restrictions to all branches matching release/*, main, or feature/*-hotfix.
• Granular actions: Grant or deny push, merge, or delete rights to individual users or teams.
• Pull‑request enforcement: Require a PR with a minimum number of approvals before merging.
• Integration with CI: When a PR is created, CI runs automatically; merge only after passing.

Section 2 – Setting Up a Release‑Branch Rule

Below is a step‑by‑step example that protects all release/* branches. The rule requires two approvals, blocks direct pushes, and disallows deletion.

1. Navigate to the repository settings – Repository Settings > Branch permissions in Bitbucket Cloud.
2. Click “Add restriction” and select “Branch name pattern”.
3. Enter the pattern: release/*.
4. Configure the actions:
   • Push: Disallow
   • Merge: Allow only via pull request
   • Delete: Disallow
5. Set PR approval rules:
   • Require at least 2 approvals.
   • Require a specific team (e.g., QA) to approve.
6. Save the restriction.

Now, any attempt to push directly to release/* fails with the message: "You do not have permission to push to this branch." Only a PR that meets the approval criteria can merge.

Section 3 – Verifying the Rule with the REST API

To audit or automate permission creation, you can use Bitbucket’s REST API. Below is a sample curl request that lists all branch restrictions for a repo.

curl -u : \
  -X GET \
  https://api.bitbucket.org/2.0/repositories///branch-restrictions

Expected response snippet:

{
  "values": [
    {
      "id": 42,
      "kind": "push",
      "pattern": "release/*",
      "users": [],
      "groups": [
        {"slug": "devs"}
      ]
    },
    {
      "id": 43,
      "kind": "merge",
      "pattern": "release/*",
      "min_approvals": 2,
      "required_approvers": ["QA"]
    }
  ]
}

Run this from a machine with network access to Bitbucket and an app password that has repository:write scope.

Section 4 – Trade‑offs and Limitations

• Administrative overhead: Managing dozens of rules can become complex; a typo in a pattern may lock out a whole team.
• Hot‑fix delays: A rule that requires two approvals can stall critical patches if the approver is unavailable.
• Learning curve: New contributors must understand the PR workflow and the meaning of “approval” in the context of the rule.
• UI vs. API sync: Rules created via the UI may not immediately reflect in the API due to caching; always re‑fetch after changes.

The key to success is to document your permission strategy, review it quarterly, and automate rule creation with scripts or CI jobs.

Actionable Takeaway

1. Identify the branches that need the toughest protection (often main or release/*). 2. Use the Branch Permissions UI or API to block direct pushes and enforce PR approvals. 3. Add a short README snippet in the repo that explains the required PR process. 4. Schedule a quarterly review of the permission list and prune any stale rules.

By treating branch permissions as code, you lock out accidental pushes, enforce peer review, and keep the mainline stable without adding manual steps to your workflow.