Automating Bitbucket PR Reviews and Checks

atlassian-cli is an independent, community open-source project, not affiliated with, endorsed by, or sponsored by Atlassian, and is not Atlassian's official CLI (acli). Product names are used only to identify compatibility.

Why automate Bitbucket PR reviews?

You can drive the entire Bitbucket PR review cycle from the terminal: list open pull requests, see who has approved, add review comments, approve, verify merge checks, and merge, without ever opening a browser tab. That is the short answer. The rest of this post shows the exact atlassian-cli commands and how to wire them into continuous integration so an unreviewed branch cannot slip through.

Review work is repetitive by nature. A reviewer opens the PR list, filters to open items, reads the diff, leaves a comment, clicks Approve, and eventually merges. Multiply that across a dozen repositories and a busy team, and the clicking adds up. Worse, the important guardrail, "this PR has enough approvals and passing builds before it merges", is easy to eyeball wrong in a hurry. Moving these steps to the command line makes them scriptable, repeatable, and testable in CI, where a failed check blocks the merge instead of relying on someone to remember.

How this differs from Atlassian's acli

atlassian-cli is an independent, community open-source project. It is not Atlassian's official CLI (acli) and is not affiliated with Atlassian. Use the official acli if you want first-party vendor support. Use atlassian-cli if you want a single free Rust binary that spans Jira, Confluence, Bitbucket, and Jira Service Management with the same flags and output formats everywhere. Everything below uses the bitbucket command group (its short alias is bb), and every command accepts the global --format and --profile flags, which is what makes CI scripting predictable.

All commands take a --workspace and a repository slug. Replace myteam with your Bitbucket workspace ID and api-service with your repository slug throughout. Numeric IDs like 123 are pull request IDs.

List and inspect open pull requests

Start where every review starts: what is open and waiting? The pr list command filters by state and limit.

# All open PRs in a repo, newest activity first
atlassian-cli bitbucket --workspace myteam pr list api-service --state OPEN --limit 20

# Machine-readable, so a script can loop over IDs
atlassian-cli bitbucket --workspace myteam pr list api-service --state OPEN --format json \
  | jq '.[] | {id: .id, title: .title, author: .author.display_name}'

To read a single pull request in full, pass its ID to pr get. The default output is a readable summary; add --format json when you want to pull specific fields out programmatically.

# Human-readable PR summary
atlassian-cli bitbucket --workspace myteam pr get api-service 123

# Full JSON payload for scripting
atlassian-cli bitbucket --workspace myteam pr get api-service 123 --format json

The JSON payload is the raw material for every check later in this post. Bitbucket Cloud returns the PR state (OPEN, MERGED, DECLINED), the author, the source and destination branches, and a participants array. Each participant carries a role (REVIEWER or PARTICIPANT), an approved boolean, and the user's details, which is exactly how you tell who still owes a review.

Because the same --format json flag works on every command in the tool, you can build a cross-repository review dashboard without any special integration. Loop over your repositories, run pr list for each, and collect the open PRs into one report. That is the kind of thing the web UI makes tedious, since it scopes you to a single repository at a time, and the kind of thing a three-line shell loop makes trivial.

Approve and comment from the terminal

Once you have read the diff, the two review actions you reach for most are approving and commenting. Both are one-liners.

# Approve the pull request (same as clicking Approve in the UI)
atlassian-cli bitbucket --workspace myteam pr approve api-service 123

# Leave a written review comment
atlassian-cli bitbucket --workspace myteam pr comment api-service 123 \
  --text "Logic looks good. Please add a test for the empty-input case before merge."

# Read the existing comment thread
atlassian-cli bitbucket --workspace myteam pr comments api-service 123

A common pattern is comment-then-approve: post your feedback, and if it is non-blocking, approve in the same breath so the author is not waiting on a second round. Because pr comment takes plain text on a flag, you can build the message from a template or a linter's output and post it automatically. Here is the full set of review verbs the CLI exposes for pull requests.

Check approval and merge status

The point of automating review is to make merge readiness a data question, not a judgement call. Since pr get --format json exposes the participants array, you can count approvals with jq and decide whether the PR clears your bar.

# How many reviewers have approved?
atlassian-cli bitbucket --workspace myteam pr get api-service 123 --format json \
  | jq '[.participants[] | select(.approved == true)] | length'

# Who still needs to approve?
atlassian-cli bitbucket --workspace myteam pr get api-service 123 --format json \
  | jq '.participants[] | select(.role == "REVIEWER" and .approved == false) | .user.display_name'

Wrap that count in a small check and you have a merge gate you can run anywhere. The --format quiet flag is handy here too: it suppresses output so a command's exit code alone drives your && logic in a script.

# Fail the script unless the PR has at least 2 approvals
APPROVALS=$(atlassian-cli bitbucket --workspace myteam pr get api-service 123 --format json \
  | jq '[.participants[] | select(.approved == true)] | length')

if [ "$APPROVALS" -lt 2 ]; then
  echo "Blocked: only $APPROVALS approval(s), need 2" >&2
  exit 1
fi
echo "OK: $APPROVALS approvals"

This turns "did enough people review it?" into a hard check. It is the same logic whether you run it locally before merging or inside a pipeline that guards the destination branch.

Enforce required approvals with branch rules

A script check is a good backstop, but the strongest guarantee comes from Bitbucket itself. Branch restrictions live on the repository and are enforced server-side for every PR that targets a protected branch, so nobody can merge around them. atlassian-cli manages these with branch protect.

# Require 2 approvals before anything merges into main
atlassian-cli bitbucket --workspace myteam branch protect api-service \
  --pattern "main" \
  --kind restrict_merges \
  --approvals 2

# Review the restrictions currently in force
atlassian-cli bitbucket --workspace myteam branch restrictions api-service

With that rule in place, the pr merge command (and the web UI, and anyone else) is held to the same standard: two approvals on a PR targeting main, or no merge. Setting the rule once through the CLI means you can commit it to a setup script and apply the identical policy across every repository in the workspace, instead of clicking through each repo's settings by hand.

Merge with a chosen strategy

When the checks pass, merge. The pr merge command takes a --strategy flag so your automation matches the target branch's history policy.

# Standard merge commit
atlassian-cli bitbucket --workspace myteam pr merge api-service 123 --strategy merge_commit

# Squash all commits into one, common for a clean main history
atlassian-cli bitbucket --workspace myteam pr merge api-service 123 --strategy squash

Bitbucket Cloud supports three strategies: merge_commit keeps every commit and adds a merge commit, squash collapses the branch into a single commit, and fast_forward moves the branch pointer forward with no merge commit. If the branch rule from the previous section is not satisfied, the merge is rejected, which is exactly the safety you want. Standardizing the strategy in a script also removes the "which button did I click?" inconsistency you get from a dropdown in the UI.

Gate merges inside a pipeline

Put the pieces together and you get a self-contained gate you can run in Bitbucket Pipelines or any CI runner. The script below confirms the PR is open, counts approvals, and only merges when the bar is met.

#!/bin/bash
# auto-merge.sh: merge a PR only when it is open and has enough approvals
set -euo pipefail

WORKSPACE="myteam"
REPO="api-service"
PR="$1"
REQUIRED=2

PR_JSON=$(atlassian-cli bitbucket --workspace "$WORKSPACE" pr get "$REPO" "$PR" --format json)

STATE=$(echo "$PR_JSON" | jq -r '.state')
if [ "$STATE" != "OPEN" ]; then
  echo "PR $PR is $STATE, nothing to do"
  exit 0
fi

APPROVALS=$(echo "$PR_JSON" | jq '[.participants[] | select(.approved == true)] | length')
if [ "$APPROVALS" -lt "$REQUIRED" ]; then
  echo "Blocked: $APPROVALS/$REQUIRED approvals" >&2
  exit 1
fi

atlassian-cli bitbucket --workspace "$WORKSPACE" pr merge "$REPO" "$PR" --strategy squash
echo "Merged PR $PR after $APPROVALS approvals"

Authenticate the runner once with a --profile that holds a Bitbucket app password or API token (see the authentication guide), and the script needs no interactive input. Pair it with the server-side branch rule from earlier and you have defense in depth: the pipeline refuses to call merge without approvals, and Bitbucket refuses the merge anyway if the rule is not met. For a longer, production-hardened version with logging and confirmation prompts, see the Bitbucket PR automation runbook. If you also want CI builds to feed into this gate, the companion post on triggering Bitbucket Pipelines from the CLI covers running and watching a pipeline before you merge.

FAQ

Related Resources