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".