Review and Merge

The commands that review a pull request or change its state: bb pr approve, bb pr unapprove, bb pr request-changes, bb pr decline, bb pr ready, bb pr merge.

See Global flags for JSON output, workspace/repository selection, and display options.

On these commands the field list is matched against the result envelope shown under JSON output, not against the PR, so --json title returns {"title": null}. Use a dotted path (--json pullRequest.state) or --jq instead.

`bb pr merge`

bb pr merge [id] [options]

[id] is the pull request ID. Omit it to merge the open PR for your current branch (how it is picked).

Options

Option	Description
`-m, --message <message>`	Merge commit message
`--close-source-branch`	Delete the source branch after merging
`--strategy <strategy>`	Merge strategy (see below)
`--dry-run`	Print the write request instead of sending it (details)

Merge strategies

Strategy	Description
`merge_commit`	Create a merge commit
`squash`	Squash all commits into a single commit
`fast_forward`	Fast-forward if possible, fail otherwise
`squash_fast_forward`	Squash commits and fast-forward
`rebase_fast_forward`	Rebase source commits onto destination and fast-forward
`rebase_merge`	Rebase source commits onto destination and create a merge commit

Omitting --strategy uses the repository’s configured merge strategy (typically merge_commit), not a CLI default. The CLI sends no strategy at all unless you pass one.

Strategy names are checked when the command runs, not by the argument parser. An unknown value fails with 5002 VALIDATION_INVALID and the message --strategy must be one of: merge_commit, squash, …. Case doesn’t matter (SQUASH works); a typo such as sqush gets a “did you mean” suggestion. Under --json that failure comes back as a JSON error envelope.

Examples

# Merge PR #42 using the repository's configured strategy
bb pr merge 42

# Squash and delete the source branch
bb pr merge 42 --strategy squash --close-source-branch

# Merge with a custom commit message
bb pr merge 42 -m "Merge feature: Add user authentication"

# Rebase and fast-forward
bb pr merge 42 --strategy rebase_fast_forward

# Capture the merge commit hash (--jq prints JSON-quoted strings, so strip them)
bb pr merge 42 --json --jq '.pullRequest.merge_commit.hash' | tr -d '"'

`bb pr approve`, `bb pr unapprove`, `bb pr decline`, `bb pr ready`

Each takes an optional pull request ID; without one they act on the open PR for your current branch. The only command-specific option is --dry-run, which prints the write request instead of sending it (details).

bb pr approve 42     # Approve
bb pr unapprove 42   # Withdraw your approval
bb pr decline 42     # Decline
bb pr ready 42       # Clear the draft flag, marking the PR ready for review
bb pr approve        # Approve the open PR for the current branch

# Any of them against an explicit repository
bb pr approve 42 -w myworkspace -r myrepo

bb pr ready is a pull request update that sets draft: false. It sends no other fields.

Bitbucket Cloud has no API to reopen a declined pull request, so there is no bb pr reopen. Open a new one with bb pr create instead.

`bb pr request-changes`

bb pr request-changes [id] [--undo] [--dry-run]

Marks the PR as “changes requested” by you, the counterpart of bb pr approve. --undo removes your change request again. Without an ID it acts on the open PR for your current branch.

bb pr request-changes 42
bb pr request-changes 42 --undo
bb pr request-changes        # the open PR for the current branch

JSON output

The commands on this page do not return the same shape. bb pr approve and bb pr unapprove return only the identifiers:

{
  "success": true,
  "pullRequestId": 42
}

bb pr request-changes adds "changesRequested": true (false with --undo).

bb pr decline, bb pr ready, and bb pr merge add the pull request exactly as the API returned it, decline and merge change the state, while ready clears draft without requesting a state change. Abridged, for bb pr merge:

{
  "success": true,
  "pullRequestId": 42,
  "pullRequest": {
    "id": 42,
    "title": "Add user authentication",
    "state": "MERGED"
  }
}

A script that reads .pullRequest after bb pr approve --json gets null. Fetch the PR separately with bb pr view 42 --json if you need its fields after approving.