Enforcing Code Quality with Bitbucket Branch Permissions: A Practical Guide

Desired Outcome

The goal is to prevent accidental or unauthorized changes to critical branches (e.g., main or release/*) by enforcing:

• Only designated users or groups can push or delete.
• Pull requests must receive a minimum number of approvals.
• All CI builds must pass before a merge is allowed.

Prerequisites

• Bitbucket Cloud or Data Center/Server instance (v7.0+).
• Repository with admin rights (or project admin for global permissions).
• Active Bitbucket Pipelines project with at least one successful build defined.
• Users/groups that will be granted push/merge rights.
• Optional: REST API access token with repository:admin scope.

Procedure

1. Define Branch Mask and Permissions (UI)

1. Navigate to the repository settings: Repository Settings > Branches > Branch Permissions.
2. Click Add a branch permission.
3. Set Branch name pattern to main (or release/* for all release branches).
4. Under Restrictions choose:
   • Push: Only admins or specific groups.
   • Delete: Only admins.
   • Merge: Allowed only via pull request (enforces merge checks).
5. Save changes.

2. Configure Merge Checks (UI)

1. Still in Branch Permissions, click Add a merge check for the same branch pattern.
2. Enable:
   • Minimum approvals: e.g., 2.
   • Build status must succeed: select the pipeline that produces a SUCCESS status.
3. Save.

3. Verify Restrictions Locally (CLI)

Run the following as a non‑admin user to confirm push is blocked.

# Replace <repo-url> with your repository HTTPS URL
# and use a non‑admin account with git credentials set.

git clone <repo-url>
cd <repo-name>
# Attempt to push directly to main
git checkout -b temp-branch
# Make a trivial change
echo "test" >> README.md
 git add README.md
 git commit -m "Test push"
 git push origin temp-branch:main

Expected output: remote: Permission denied or similar. If the push succeeds, the permission is mis‑configured.

4. Verify Merge Checks via Pull Request (Web UI)

1. Create a PR from temp-branch to main.
2. Observe that the Merge button is disabled until:
• At least two reviewers approve the PR.
• Bitbucket Pipelines reports a successful build.
3. Once both conditions are met, the button becomes enabled.

5. Optional: Use REST API for Automation

For large teams, scripting the permission setup can save time.

# Replace placeholders
API_URL="https://api.bitbucket.org/2.0/repositories/<workspace>/<repo_slug>"
TOKEN="Bearer <admin-access-token>"

# Create branch permission
curl -X POST "$API_URL/branch-restrictions" \
  -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "push",
    "pattern": "main",
    "users": ["[contact removed]"],
    "groups": ["dev-team"]
  }'

Check the response for a 201 status. If you receive a 400, review the JSON schema or pattern syntax.

Expected Checks

• Direct push attempts from non‑admin accounts return Permission denied.
• Pull requests show merge disabled until approvals and build status are satisfied.
• Repository settings page lists the branch permission and merge check entries.
• Pipeline runs are triggered automatically on PR creation.

Recovery Options

• Emergency hotfix: Grant yourself temporary push rights via the UI or API, perform the hotfix, then revoke the permission.
• Pattern mis‑configuration: If the branch mask unintentionally blocks all feature branches, edit the pattern from release/* to release/* (ensuring correct regex) or remove the permission temporarily.
• Rollback permission changes: Delete the branch restriction via UI (Branch permissions > Delete) or API (DELETE <restriction-id>).

Limitations

• Bitbucket Cloud and Data Center/Server differ slightly in REST endpoints and UI layout; adjust URLs accordingly.
• Regex patterns are case‑sensitive; verify that the pattern matches your branch naming convention.
• Permissions are inherited from project-level settings; ensure no conflicting rules exist at the project level.

Practical Check

After configuring, perform a quick sanity test: create a new feature branch, push, open a PR, and confirm the merge button remains disabled until approvals and build pass. If all checks succeed, the protection is in place.