Scaling Bitbucket Branch Permissions: Balancing Control and Velocity

The Core Problem: Why Default Permissions Don't Scale

Most teams start with Bitbucket's default branch model: everyone can push to main, pull requests are optional, and merge checks are nonexistent. That works for a handful of developers. Once you hit multiple squads, compliance requirements, or a regulated release cadence, the lack of guardrails shows up as broken builds, unreviewed hotfixes, and frantic rollback exercises.

The fix isn't locking everything down. It's designing a permission layer that matches your release rhythm — protecting the branches that matter while keeping feature work frictionless. Bitbucket Cloud and Data Center both offer the building blocks (branch restrictions, merge checks, CODEOWNERS), but they differ in scope, inheritance, and automation surface. Understanding those differences upfront saves months of retrofit work.

Building a Layered Strategy: Restrictions, Checks, and Ownership

Branch Restrictions: The Gatekeepers

Branch restrictions control who can push, merge, rewrite history, or delete a branch or pattern. In Data Center you can set them at the project level and have repositories inherit; in Cloud you must configure each repository individually (or script it via REST/Terraform). Behavior is stable across recent versions, but verify exact UI labels against your deployment.

Typical pattern:

• main and release/*: no direct pushes, no history rewrite, no delete. Only a release-managers group can merge.
• hotfix/*: push restricted to platform-leads, but still require a green build.
• feature/*: no push restrictions — developers own their branches.

Merge Checks: The Quality Gate

Merge checks run on pull requests and can be required or optional per branch pattern. Both editions support minimum approvals, successful builds, task completion, and no merge conflicts. Data Center adds reset approvals on new commits and custom merge check plugins.

Key insight: CODEOWNERS does not block merges by itself. It only auto-assigns reviewers. To enforce code-owner sign-off, pair a CODEOWNERS file with a minimum approvals merge check configured to count code-owner approvals.

CODEOWNERS: Routing Reviews Without Bottlenecks

Supported in Cloud and Data Center 7.12+. Place the file at .bitbucket/CODEOWNERS or docs/CODEOWNERS. Example:

# .bitbucket/CODEOWNERS
/src/db/       @db-team
/src/api/      @backend-team
/docs/         @tech-writers

When a PR touches /src/db/migration.sql, @db-team is auto-assigned. If you require two approvals and set the merge check to count code-owner approvals, the PR cannot merge until a DB team member approves.

Worked Example: Protecting Main, Releases, and Hotfixes

Below is a concrete configuration you can replicate in a test repository. Adjust group names to match your identity provider.

Branch Pattern	Push Restriction	Merge Checks (Required)	Merge Strategy
main	No one (only merge via PR)	2 approvals (1 code owner), green build, all tasks resolved, no conflicts	Merge commit (default)
release/*	Group release-managers	2 approvals, green build, tasks resolved	Merge commit
hotfix/*	Group platform-leads	1 approval, green build	Squash only
feature/*	None	1 approval, green build	Fast-forward only

Verification steps (run in your test repo):

1. Create the branch restrictions via UI or POST /rest/branch-utils/1.0/projects/{projectKey}/repos/{repoSlug}/branch-restrictions.
2. Add the CODEOWNERS file to .bitbucket/CODEOWNERS on main.
3. Open a PR from feature/new-api touching /src/api/. Confirm @backend-team is auto-assigned.
4. Attempt to push directly to main — expect rejection.
5. Merge the PR with only one approval — expect merge check to block.
6. Add second approval from a code owner, ensure build passes — merge should succeed.

Use GET /rest/branch-utils/1.0/projects/{projectKey}/repos/{repoSlug}/branch-restrictions to inspect effective permissions and compare with UI.

Trade-offs: Centralized Control vs. Developer Velocity

• Project-level inheritance (Data Center only) reduces admin overhead for multi-repo orgs. Cloud teams must automate per-repo configuration or accept drift.
• Reset approvals on new commits (Data Center) prevents stale approvals but creates churn on active PRs. Enable only if your compliance regime demands it.
• Squash merges simplify history but lose commit granularity, making git bisect and targeted reverts harder. Reserve for hotfix/* and short-lived feature branches.
• Audit retention: Cloud keeps 90 days; Data Center is configurable. If you need longer trails for compliance, plan a SIEM forwarder in Data Center.
• Terraform provider is community-maintained. Resource coverage for merge checks and CODEOWNERS is incomplete. Test terraform plan cycles in staging before relying on it for drift detection.

Actionable Closing: Implement, Verify, Iterate

1. Pick one repository as a pilot. Apply the table above, substituting your groups.
2. Run the six verification steps. Document any gaps (e.g., CODEOWNERS not counting as approvals).
3. If on Data Center, enable audit logging for Branch permission changed events and confirm entries appear in Administration > Audit log.
4. Roll out to remaining repos via scripted REST calls or Terraform. Schedule a quarterly drift check: compare API output with desired state.
5. Revisit merge strategies after two sprints. If squash merges on feature/* are causing revert pain, switch to fast-forward.

Branch permissions are not set-and-forget. They evolve with your team structure, compliance scope, and release cadence. Treat them as infrastructure: version-controlled, tested, and monitored.