Bitbucket Cloud: Repositories, Pull Requests and Branch Rules

Bitbucket Cloud (Atlassian) is a Git host that fits teams already using Jira and Confluence. Repositories live in projects inside a workspace, and the workspace is where you manage members, billing and policy. The goal of this post is a workflow where nobody pushes directly to main, every change is reviewed and built, and every commit is traceable to a ticket.

Versions in use on this date. Git 2.39 (December 2022) and Bitbucket Cloud. Some merge-check features depend on your plan (Free, Standard or Premium), so check the plan comparison before designing around them.

Structure and flow

flowchart TB
  WS[Workspace acme-workspace<br/>members, groups, billing, SSO] --> PRJ[Project SHOP]
  PRJ --> REPO[Repository shop-api]
  DEV[Developer] -->|SSH key| BR[feature/SHOP-142-health-check]
  BR -->|push| REPO
  BR -->|open pull request| PR[Pull request]
  PR --> CHK{Merge checks}
  CHK --> A[Approvals - at least 1]
  CHK --> B[Pipeline build passes]
  CHK --> C[No unresolved tasks or comments]
  A --> OK[Merge allowed]
  B --> OK
  C --> OK
  OK -->|squash or merge commit| MAIN[main branch protected]
  JIRA[Jira issue SHOP-142] <-->|key in branch or commit| PR
  MAIN --> DEPLOY[Pipeline deploys main]

First steps

ssh-keygen -t ed25519 -C "raviteja@laptop" -f ~/.ssh/id_ed25519_bitbucket
cat ~/.ssh/id_ed25519_bitbucket.pub          # add under Personal settings, SSH keys
ssh -T git@bitbucket.org                     # should greet you by username

git clone git@bitbucket.org:acme-workspace/shop-api.git
cd shop-api
git switch -c feature/SHOP-142-health-check
git commit -am "SHOP-142 add health check endpoint"
git push -u origin feature/SHOP-142-health-check

Putting the Jira issue key (SHOP-142) in the branch name, commit message or pull request title links the work to the ticket, and the Jira development panel then shows branches, pull requests, builds and deployments. Connect Bitbucket to Jira once from the Jira side (Apps, Manage apps).

Protect main

Under Repository settings, Branch restrictions (or workspace-level rules on higher plans), add a rule for main:

Setting	Recommended value
Write access (push directly)	Nobody (so all changes go through pull requests)
Merge via pull request	Developers group
Rewriting history (force push)	Blocked
Deleting the branch	Blocked
Minimum approvals	1, or 2 for production repositories
Passing builds	Required, with at least the latest build green
Unresolved tasks	Must be resolved

Also enable Reset approvals when the source branch is modified, so someone cannot approve and then push different code. Choose a merge strategy per repository: squash gives one commit per change and a short history; merge commit keeps detail; fast-forward keeps history linear without a merge commit. Squash plus a descriptive pull request title is a good default.

Default reviewers (Repository settings, Default reviewers) fill in the right people automatically, and you can add “default reviewers for specific paths” with a rule for infra/** to make the platform team review infrastructure changes. This is the Bitbucket equivalent of code owners.

A good pull request

1. Small and focused, ideally under about 400 changed lines.
2. Title with the Jira key and a short imperative summary; description covers what, why, how it was tested, and rollback.
3. Pipeline runs on the pull request (next post), and the author fixes failures before asking for review.
4. Reviewers leave comments, mark tasks for must-fix items, and approve only when satisfied.
5. Merge with the chosen strategy, tick Close source branch, and let the pipeline deploy from main.

Access and account security

• Enforce two-step verification for the workspace and use SSO through Atlassian Access if you have it.
• Use groups (developers, admins, contractors) rather than adding individuals to repositories, and set the repository’s default access to “no access”.
• For automation, use repository or workspace access tokens or app passwords scoped to the minimum (repository read, pipeline write). Do not use a personal account for CI.
• Turn on secret scanning (push protection) where your plan supports it, and keep secrets in secured pipeline variables.
• Review members and tokens each quarter.

Common situations

Situation	What to do
Branch behind main	git fetch origin && git rebase origin/main, then git push --force-with-lease to your own branch
Pushed to the wrong branch	Revert on that branch through a pull request; do not rewrite shared history
Merge conflict in the pull request	Rebase or merge main into your branch locally, resolve, push
Need to undo a merged change	git revert <merge-or-squash-sha> in a new pull request
Large file committed	Remove it with git filter-repo before it spreads, and consider Git LFS for binaries
Pipeline blocks merge unexpectedly	Open the build link on the pull request; a stale or cancelled build is a common cause

Migrating from or to other hosts

Import from GitHub or GitLab with Create, Import repository, which keeps history but not pull requests, so close out open reviews before the move. Update remotes with git remote set-url origin git@bitbucket.org:acme-workspace/shop-api.git, move CI variables manually, and re-create branch rules; they do not travel with the repository.