bb (Bitbucket CLI): Pull Requests and Auth
bb is a Bitbucket command-line client whose pr subcommands open and list pull requests using an app password or access token.
Bitbucket Cloud automation uses a CLI (bb) plus an app password or repository access token. The auth and pr subcommands mirror gh/glab but with Bitbucket credential rules.
What it does
bb authenticates to Bitbucket with bb auth login (username plus app password, or an access token), then bb pr create opens a pull request from a source branch to a destination branch and bb pr list shows open ones.
Common usage
# authenticate with a Bitbucket app password (non-interactive via env)
export BITBUCKET_USERNAME="ci-bot"
export BITBUCKET_APP_PASSWORD="$BB_APP_PW"
# open a PR
bb pr create --source feature-x --destination main --title "Add feature X"
bb pr listOptions
| Command / Flag | What it does |
|---|---|
| bb auth login | Store Bitbucket credentials |
| --source <branch> | Source branch for the PR |
| --destination <branch> | Target branch (Bitbucket calls it destination) |
| --title <t> | PR title |
| BITBUCKET_USERNAME | Env var: Bitbucket account username |
| BITBUCKET_APP_PASSWORD | Env var: app password used as the credential |
In CI
Bitbucket Cloud rejects your account password over the API; you must use an app password or a repository/workspace access token. Set BITBUCKET_USERNAME plus BITBUCKET_APP_PASSWORD (or the token) in the environment so the CLI is non-interactive. Note Bitbucket uses source/destination, not head/base.
Common errors in CI
"401 Unauthorized" or "Invalid or missing credentials" means the app password/token is wrong or you used your login password (unsupported). "403 Forbidden" means the credential lacks pullrequest:write scope. "400 Bad Request ... branch not found" means the source branch was not pushed. Repeating a PR gives "duplicate ... pull request already exists".
Using this in CI
CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.
- uses: actions/checkout@v4
with:
fetch-depth: 0 # history, tags, and git describe all need this
- run: |
git rev-parse --is-shallow-repository # expect false
git rev-parse --abbrev-ref HEAD # prints HEAD when detached