Set a new value for the Pipelines build number

Updating the Pipelines build number

You can use the Bitbucket REST API to set the Pipelines build number $BITBUCKET_BUILD_NUMBER to a higher value. You might want to do this if you are moving from another build tool where you already have built versions of your software with a higher build number.


  1. Log in to Bitbucket and go to your avatar on the bottom left-hand side, select a workspace, then go to Personal Settings > App passwords.

  2. Create a new app password with permission to "edit variables" in Pipelines. Copy the new password to your clipboard.

  3. Use curl to PUT to the Pipelines build_number config API:

1 2 3 4 curl -v -H 'Content-Type: application/json' -XPUT \ -d '{ "next": 1000 }' \ --user 'USERNAME:PASSWORD' \ ''

In the example above, you will need to replace:

  • 1000 with the next desired build number

  • USERNAME with your Bitbucket username (note there are two instances of USERNAME in the command)

  • PASSWORD with the app password you generated and copied above

  • REPONAME with the slug of your repository.

If it worked correctly, Bitbucket will respond with the following:

1 {"type": "pipeline_build_number", "next": 1000}

The next Pipelines build you run will use this as its build number.

Error responses

Potential error responses include:

  • HTTP/1.1 401 Unauthorized – this comes back as an HTTP header if Bitbucket cannot identify your username. Make sure you update the command above to have the correct username in both the URL and --user parameter.

  • Your credentials lack one or more required privilege scopes – you need to ensure your app password has the permission to edit Pipelines variables.

  • An invalid field was found in the JSON payload – you need to ensure your JSON payload matches the format above, a single object with a next field with an integer value (type is optional).

  • The request body contains invalid properties - your build number is lower than existing builds in Pipelines.


There is no way to update the build number through the Bitbucket web UI. This change is only possible through the Bitbucket REST API.

You cannot set the build number to a number that is lower than any existing build result in the repository. It is not currently possible to delete Pipelines builds, so we need to ensure the future build number will not clash with any existing build.

Additional Help