Guarding Your Codebase: Using Bitbucket Branch Permissions to Control Push Access

Why Branch Permissions Matter

In a fast‑moving team, a single accidental push can break a build, expose sensitive data, or roll out a buggy feature. Bitbucket’s Branch Permissions let you lock down who can write to which branches, ensuring that only authorized users or automated pipelines can modify critical code paths.

What Branch Permissions Actually Do

Branch Permissions are rules attached to a repository or project that define:

• Who can push to a branch or a set of branches.
• Whether pull‑request approvals are required.
• If merge checks (e.g., successful Pipelines run) must pass before a merge.

They replace the older “branch restriction” terms and are stored in branch-restrictions objects. You can view or edit them in the UI under Settings > Branches > Branch Restrictions or via the REST API.

Concrete Use‑Case: Protecting Release Branches

Suppose your team follows GitFlow: develop is the integration branch, while any branch matching release/* is a candidate for a production release. You want to:

• Allow only QA and Release Managers to push directly to release/*.
• Require that every pull request targeting a release/* branch passes the Build & Test pipeline.

Here’s how to set it up:

1. Define a regex rule: In the UI, add a new restriction with the pattern ^release/.*. This matches any branch that starts with release/.
2. Set the allowed actors: Choose the Only these users and groups option and add the QA and Release Manager groups.
3. Enable merge checks: Check the Require successful Pipelines box and select the pipeline that runs your build and tests.
4. Save. The rule will now block any other user from pushing directly to a release branch and will enforce a pipeline run before merges.

Result: developers can still create feature branches (e.g., feature/xyz) but cannot push to release/* without proper approval and CI validation.

Verifying the Configuration

After setting up the rule, confirm it’s active:

1. UI check: Navigate to Settings > Branches > Branch Restrictions and ensure your ^release/.* rule appears with the correct user list.
2. API check: Run the following curl command from a machine that can reach Bitbucket. Replace placeholders with your values.

   curl -u <username>:<app_password> \
     https://api.bitbucket.org/2.0/repositories/<workspace>/<repo_slug>/branch-restrictions
   

   The JSON response will contain an array of restrictions; look for the one with the pattern field matching ^release/.*.

Risk check: If you accidentally block your own user, you can still create a new branch, push, and then remove the restriction via the API or UI.

Trade‑Offs and Limitations

• Developer friction: Over‑restricting can lead to bottlenecks. If a developer needs to create a temporary release branch, they must request permission or use a feature branch that is later merged.
• No inheritance to forks: Branch permissions are repository‑specific; a forked repo will need its own rules.
• Legacy terminology: Some older repos still expose the branch restriction API endpoints; ensure you’re using /branch-restrictions for new repos.
• Regex complexity: A poorly written pattern can either be too permissive or too restrictive. Test patterns against expected branch names before applying.

Practical Takeaway

By combining regex‑based branch permissions with Pipeline merge checks, you can enforce a robust gate that protects critical branches from accidental pushes while still allowing developers to innovate on feature branches. Start with a single, clear rule—such as protecting release/*—and iterate as your workflow matures.

Remember: always verify after changes, keep your API tokens secure, and document your permission strategy so new team members understand the branch protection rules.