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, -w, --workspace, -r, --repo.

---

bb status list

List the build statuses reported on a commit.

bb status list <sha> [options]

Arguments

Argument	Description
sha	Commit hash (full or abbreviated, e.g. abc1234)

Options

Option	Description
-w, --workspace <workspace>	Workspace
-r, --repo <repo>	Repository
--limit <number>	Maximum number of statuses (default: 25)
--all	List all statuses (overrides --limit)
--json	Output as JSON

Examples

bb status list abc1234
bb status list abc1234 --all

# Stable JSON envelope: { 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

• The table shows the status key, state (colored: green SUCCESSFUL, red FAILED, yellow INPROGRESS, gray STOPPED), name, description (truncated to 40 characters; disable with --no-truncate), and URL — the same rendering as bb pr checks.
• A 404 returns an actionable “Commit <sha> not found” error.

---

bb status set

Create or update a build status on a commit.

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

Arguments

Argument	Description
sha	Commit hash (full or abbreviated)

Options

Option	Description
-w, --workspace <workspace>	Workspace
-r, --repo <repo>	Repository
--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 SUCCESSFUL, FAILED, INPROGRESS, STOPPED (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
--json	Output as JSON

Examples

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

# Stable JSON envelope: { 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

#!/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

• Idempotent per key: the CLI first POSTs a new status; if Bitbucket rejects it because a status with that key already exists on the commit (typical on CI re-runs), it automatically falls back to updating the existing status via PUT. Repeated bb status set calls with the same --key are therefore always safe.
• --state is validated client-side against the API enum; an invalid value lists the allowed states.
• 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

• Commit Commands — list and inspect the commits themselves.
• CI/CD Integration — using bb inside pipelines.
• Scripting & Automation — JSON envelopes, --jq, exit codes.