Skip to content
Bitbucket CLIBitbucket CLI

Status Commands - Commit Build Statuses

Manage build statuses on commits — the red/green/yellow indicators Bitbucket shows next to commits and pull requests. bb status set is built for CI scripts: it is non-interactive, idempotent per status key, and JSON-friendly.

Status commands operate at repository scope. Run them inside a cloned Bitbucket repository, or pass -w, --workspace <workspace> and -r, --repo <repo> explicitly.

Global options available on all status commands: --json [fields], --jq <expression>, --no-color, --no-unicode, --no-truncate, --locale <locale>, -w, --workspace, -r, --repo.

A <sha> is a full 40-character hash or any abbreviated prefix (abc1234). --json output is wrapped in an envelope keyed by workspace and repoSlug; the # → comments below show each shape.

bb status list

Section titled “bb status list”

List the build statuses reported on a commit.

Terminal window
bb status list <sha> [options]

Options

Section titled “Options”
Option Description
--limit <number> Maximum number of statuses (default: 25)
--all List all statuses (overrides --limit)

Examples

Section titled “Examples”
Terminal window
bb status list abc1234
bb status list abc1234 --all


# → { workspace, repoSlug, commit, count, statuses }
bb status list abc1234 --json


# States only, via built-in --jq
bb status list abc1234 --json --jq '.statuses[].state'

Notes

Section titled “Notes”
  • Columns: status key, state (colored: green SUCCESSFUL, red FAILED, yellow INPROGRESS, gray STOPPED), name, description (truncated to 40 characters; disable with --no-truncate), and URL.
  • bb pr checks colors states the same way but renders a different table: STATUS / NAME / DESCRIPTION / UPDATED, with the state shown as OK passed / FAIL failed / RUN running / STOP stopped rather than the raw state string.
  • An unknown sha returns Commit abc1234 not found in acme/api.

bb status set

Section titled “bb status set”

Create or update a build status on a commit. <sha> is a full or abbreviated hash.

Terminal window
bb status set <sha> --key <key> --state <state> [options]

Options

Section titled “Options”
Option Description
--key <key> Required. Unique status key, e.g. BB-DEPLOY. Re-running with the same key updates the existing status.
--state <state> Required. One of FAILED, INPROGRESS, STOPPED, SUCCESSFUL (case-insensitive)
--url <url> Link back to the build system
--name <name> Build identifier, e.g. BB-DEPLOY-1
--description <description> Short build description
--refname <refname> Ref the build ran on, e.g. a branch name

Examples

Section titled “Examples”
Terminal window
bb status set abc1234 --key CI --state INPROGRESS
bb status set abc1234 --key CI --state SUCCESSFUL --url https://ci.example.com/builds/42
bb status set abc1234 --key LINT --state FAILED --description "ESLint found 3 errors" --refname main


# → { workspace, repoSlug, commit, status }
bb status set abc1234 --key CI --state SUCCESSFUL --json --jq '.status.state'

CI recipe: wrap a build in INPROGRESS → SUCCESSFUL/FAILED

Section titled “CI recipe: wrap a build in INPROGRESS → SUCCESSFUL/FAILED”
#!/usr/bin/env bash
set -euo pipefail


SHA="$(git rev-parse HEAD)"
KEY="CI"
URL="https://ci.example.com/builds/${BUILD_ID:-local}"


# Mark the commit as building before the work starts
bb status set "$SHA" --key "$KEY" --state INPROGRESS --url "$URL" \
  --name "CI Build ${BUILD_ID:-local}" --refname "$(git branch --show-current)"


# Run the build; report the result either way
if ./run-build.sh; then
  bb status set "$SHA" --key "$KEY" --state SUCCESSFUL --url "$URL"
else
  bb status set "$SHA" --key "$KEY" --state FAILED --url "$URL" \
    --description "Build failed; see logs"
  exit 1
fi

Notes

Section titled “Notes”

  • Idempotent per status key: the CLI first POSTs a new status. If the POST is rejected for anything other than an auth or not-found failure — most commonly because a status with that key already exists on the commit, the normal case on CI re-runs — it retries as a PUT against the existing key. Repeated bb status set calls with the same --key are therefore always safe.

  • --state is upper-cased before validation, so successful and SUCCESSFUL both work. An invalid value lists the allowed states and, when the input is close to a valid one, suggests it:

    --state must be one of: FAILED, INPROGRESS, STOPPED, SUCCESSFUL
    (Did you mean SUCCESSFUL?)

  • On success the CLI prints ✓ Status <key> set to <state> on <short-sha>; with --json it returns the resulting status resource wrapped in { workspace, repoSlug, commit, status }.

  • These statuses are what bb pr checks aggregates for a pull request.

See also

Section titled “See also”