{"id":12892,"library":"bitbucket-build-status","title":"Bitbucket Build Status CLI","description":"The `bitbucket-build-status` package provides a command-line interface (CLI) tool, `bbuild`, for programmatically posting build statuses to Bitbucket Cloud and Bitbucket Server. Its primary function is to update the build status for a specific commit in a Bitbucket repository, indicating states like INPROGRESS, SUCCESSFUL, or FAILED. The current stable version is 1.2.0, last published in February 2020, indicating a stalled release cadence with no recent updates. Key differentiators include its simplicity as a standalone CLI tool and explicit support for both Bitbucket.org and self-hosted Bitbucket Server instances via a base URL option. It facilitates integration into CI/CD pipelines where direct API interaction for build status updates is needed without relying on a full-featured Bitbucket API client library.","status":"maintenance","version":"1.2.0","language":"javascript","source_language":"en","source_url":null,"tags":["javascript"],"install":[{"cmd":"npm install bitbucket-build-status","lang":"bash","label":"npm"},{"cmd":"yarn add bitbucket-build-status","lang":"bash","label":"yarn"},{"cmd":"pnpm add bitbucket-build-status","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is strictly a command-line interface (CLI) tool. It does not export any functions, classes, or objects for programmatic import and use within JavaScript/TypeScript applications.","wrong":"import { bbuild } from 'bitbucket-build-status';","symbol":"CLI Usage","correct":"Access directly via the `bbuild` command in your terminal after global npm installation."},{"note":"Attempts to `require` or `import` this package as a module will result in errors, as its functionality is only exposed through the `bbuild` executable on the command line.","wrong":"const BitbucketBuildStatus = require('bitbucket-build-status');","symbol":"Programmatic API","correct":"This package is not designed for programmatic API calls."},{"note":"As a CLI-only utility, `bitbucket-build-status` does not provide TypeScript type definitions for programmatic consumption by other modules.","wrong":"import type { BuildStatusOptions } from 'bitbucket-build-status';","symbol":"TypeScript Types","correct":"No programmatic types are available as there is no exportable API."}],"quickstart":{"code":"#!/bin/bash\n\n# NOTE: Replace placeholders with your actual values\nBITBUCKET_SERVER_URL=\"https://bitbucket.your-company.com\"\nREPO_OWNER=\"your_owner_or_team\"\nREPO_SLUG=\"your-repository\"\nCOMMIT_HASH=\"a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0\"\nBUILD_KEY=\"MY-CI-BUILD\"\nBUILD_NAME=\"My Project Build\"\nBUILD_URL=\"https://ci.your-company.com/build/123\"\nBUILD_DESCRIPTION=\"Latest build from CI/CD pipeline\"\nBITBUCKET_USERNAME=\"ci_user\"\nBITBUCKET_APP_PASSWORD=\"your_bitbucket_app_password\"\n\n# Example 1: Set status to INPROGRESS for Bitbucket Server\n# Use process.env.BITBUCKET_APP_PASSWORD for actual secrets\nbbuild \\\n  --server \"${BITBUCKET_SERVER_URL}\" \\\n  --owner \"${REPO_OWNER}\" \\\n  --repo \"${REPO_SLUG}\" \\\n  --commit \"${COMMIT_HASH}\" \\\n  --state \"INPROGRESS\" \\\n  --key \"${BUILD_KEY}\" \\\n  --name \"${BUILD_NAME}\" \\\n  --url \"${BUILD_URL}\" \\\n  --description \"${BUILD_DESCRIPTION}\" \\\n  --username \"${BITBUCKET_USERNAME}\" \\\n  --password \"${BITBUCKET_APP_PASSWORD}\"\n\n# Example 2: Update status to SUCCESSFUL for Bitbucket Cloud (omit --server)\nbbuild \\\n  --owner \"${REPO_OWNER}\" \\\n  --repo \"${REPO_SLUG}\" \\\n  --commit \"${COMMIT_HASH}\" \\\n  --state \"SUCCESSFUL\" \\\n  --key \"${BUILD_KEY}\" \\\n  --name \"${BUILD_NAME} - Final\" \\\n  --url \"${BUILD_URL}/report\" \\\n  --description \"Build passed all tests!\" \\\n  --username \"${BITBUCKET_USERNAME}\" \\\n  --password \"${BITBUCKET_APP_PASSWORD}\"","lang":"bash","description":"Demonstrates how to use the `bbuild` command to post build statuses for both Bitbucket Server and Bitbucket Cloud."},"warnings":[{"fix":"For Bitbucket Server >= 7.14, verify if the tool's API calls are compatible with the current API (e.g., using projectKey and repositorySlug in the URL). Consider migrating to a more actively maintained Bitbucket API client library if issues persist.","message":"This tool was last updated in February 2020 (v1.2.0). Bitbucket Server (and potentially Cloud) APIs have evolved, with some build status endpoints deprecated in Bitbucket Server 7.14 and newer versions. This CLI might be using outdated API endpoints, leading to `404 Not Found` or `400 Bad Request` errors for newer Bitbucket installations.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Generate a Bitbucket App Password (via Personal settings -> App passwords) with sufficient 'Account: Write' and 'Repositories: Write' permissions, and use this as the `--password` value.","message":"Authentication with a Bitbucket Cloud account often requires an App Password instead of your regular account password, especially if 2FA is enabled or direct password authentication for APIs is restricted. Using a regular password may result in `401 Unauthorized` errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always explicitly set `--server` with the base URL of your Bitbucket Server instance for self-hosted deployments. For Bitbucket Cloud, ensure it is omitted or set correctly if your project is not on bitbucket.org.","message":"The `--server <url>` option is crucial for targeting a Bitbucket Server instance; omitting it defaults to Bitbucket Cloud (api.bitbucket.org). Misconfiguring this can lead to build statuses being sent to the wrong platform or `404 Not Found` errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure the `--state` argument uses one of the exact specified values. Truncate `url`, `key`, `name`, and `description` values if they exceed their respective character limits.","message":"The supported states for a build status are strictly `INPROGRESS`, `SUCCESSFUL`, or `FAILED`. Using any other string will result in an API error. Field lengths are also restricted (e.g., `url` to 450 chars, `key`, `name`, `description` to 255 chars).","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Verify username and ensure an App Password (with 'Account: Write' and 'Repositories: Write' permissions) is used for Bitbucket Cloud. For Bitbucket Server, ensure the user account has `LICENSED` permission or higher.","cause":"Invalid authentication credentials (username or password). For Bitbucket Cloud, this often means a regular password was used instead of an App Password, or the App Password lacks necessary permissions.","error":"Error: 401 Unauthorized"},{"fix":"Double-check the `--commit`, `--repo`, and `--owner` values. If targeting Bitbucket Server, confirm API compatibility and consider the API changes in newer Bitbucket Server versions as a potential cause.","cause":"The specified commit, repository, or owner could not be found, or the Bitbucket API endpoint used by the tool is no longer valid for the target Bitbucket instance (especially Bitbucket Server versions >= 7.14).","error":"Error: 404 Not Found"},{"fix":"Consult `bbuild --help` and ensure all mandatory options are present. These typically include `--commit`, `--repo`, `--state`, `--key`, `--name`, `--url`, `--username`, and `--password`.","cause":"Essential arguments like `--commit`, `--repo`, `--state`, `--key`, or `--url` were not provided in the command line or the `--file` JSON.","error":"Error: Missing required argument: --commit"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"bbuild"}