Enforcing Code Quality: Bitbucket Branch Protection for CI and Approvals

Enforce Merge Requirements Before Code Reaches Main

Branch protection rules in Bitbucket prevent merges to critical branches like main or master unless specific conditions—such as required peer approvals and successful Continuous Integration (CI) checks—are met. To configure this, navigate to Repository Settings > Branch permissions.

Granular Control with Branch Patterns

Permissions are scoped using glob-style pattern matching. For instance, setting a rule on the pattern feature/* applies to all branches starting with feature/, allowing granular control across different development streams without affecting main.

Configuration Example: Strict Main Branch

To ensure the main branch requires high quality, configure the following settings for the pattern main:

• Minimum approvals: 2
• Check statuses: Required
• Linear history: Required (enforces squash or rebase merges)
• Allow administrators to bypass: Disabled

This setup mandates two reviews, successful CI runs, and a clean, linear commit history before any code enters main.

Verifying Status Check Integration

The 'Check statuses' feature requires your CI tool (e.g., Bitbucket Pipelines, Jenkins) to report the status back to the Bitbucket API using the specific commit SHA. If the CI tool fails to report the correct status, the merge button will remain active even if the pipeline failed, leading to incorrect merges.

Practical Check: Create a pull request targeting main where the associated CI job is intentionally configured to fail. Verify that the 'Merge' button in the pull request view is greyed out until the status check reports SUCCESS.

Limitations and Common Pitfalls

• Admin Override: Branch protection is bypassed by users with administrative permissions unless the 'Allow administrators to bypass' setting is explicitly disabled.
• Approval Bottlenecks: Overly strict or narrowly defined approval requirements can halt development if required reviewers are unavailable.
• History Integrity: Enforcing 'Linear history' prevents standard merge commits, requiring developers to use squash or rebase when merging feature branches.

If you modify these settings, the state of the protected branch changes. There is no direct rollback mechanism within the UI; configuration changes must be reverted manually to the previous valid state.