Set a new value for the Pipelines build number

Still need help?

The Atlassian Community is here for you.

Ask the community

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 into Bitbucket and select your avatar on the top navigation bar, then select Personal settings.

  2. From the Personal settings page, under Access management, select App passwords.

  3. Create a new app password with permission to "edit variables" in Pipelines. Copy the new password to your clipboard.  You will be using your username and the app password, not the app password label.

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

    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:

{"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 can't identify your username. Make sure you change the command above to have the correct username in both the URL and the --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.

  • Authentication Error - "remote: Invalid username or password" - You may be using the app password label, not your username. Your Bitbucket username is listed under Bitbucket profile settings on your Bitbucket Personal settings page.


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

You can't 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.

Last modified on Sep 20, 2022

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.