Secure Your Production Code with Bitbucket Cloud Branch Permissions

Why Branch Permissions Matter

In a fast‑moving team, the temptation to push directly to main or a release branch can lead to accidental regressions. Bitbucket Cloud’s Branch Permissions let you lock down who can write to, delete, or merge into specific branches, ensuring that only vetted code reaches production.

Setting Up a Basic Protection Rule

1. Navigate to the repository you own or administer.
2. Click Repository settings → Branch permissions in the left‑hand menu.
3. Press Add a branch permission and choose Write access (or Delete if you want to lock deletion).
4. In the Branch name pattern field, enter main (or release/* for all release branches).
5. Under Require reviewers, set the minimum number of approvals (e.g., 1).
6. Optionally, enable Require a successful build to enforce CI checks before merging.
7. Click Save.

After saving, any push to main from a non‑admin account will be rejected. Pull requests will be blocked until the required reviewers approve and the pipeline passes.

API‑Based Example

For automation, you can create a permission rule via the REST API. Replace <repo-id> and <workspace> with your values.

curl -X POST \
  https://api.bitbucket.org/2.0/repositories/<workspace>/<repo-id>/branch-restrictions \
  -u <username>:<app-password> \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "write",
    "pattern": "main",
    "users": [""],
    "approvals": 1,
    "builds": {"required": true}
  }'}

Note: the API requires an app password with the repository:write scope.

How It Works With Pipelines

Bitbucket Cloud integrates branch permissions with Pipelines. When a pull request targets a protected branch, the merge button remains disabled until:

• The pipeline finishes successfully.
• All required reviewers have approved.
• Any additional merge checks (e.g., no conflicts) pass.

Result: broken code never lands in production, and reviewers are forced to validate changes.

Trade‑Offs and Gotchas

Consideration	Impact
Over‑restrictive rules	Can stall feature releases if the rule blocks legitimate contributors.
Admin override	Repository admins can bypass the rule; document rules for audit.
Tagging & PR creation	Branch permissions do not affect tags or creating pull requests; add separate settings if needed.
Bitbucket Server	Feature is only in Bitbucket Cloud; Server uses a different permission model.

Actionable Checklist

1. Create a test rule on a non‑critical branch (e.g., dev-test) to verify behavior.
2. Apply the rule to main or your release branches once you’re confident.
3. Document the rule set in your repo’s README or a dedicated SECURITY.md.
4. Periodically review the list of admins who can override rules.
5. Combine branch permissions with required reviewers and CI checks for maximum safety.

By following these steps, you can protect critical branches while maintaining a healthy CI/CD workflow.