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.

Steps

1. Log in to Bitbucket.

2. Create an API token with at least the scope 'admin:pipeline:bitbucket' by following the steps from Create an API token (see more information on API tokens).

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

   curl -v -H 'Content-Type: application/json' -XPUT \ -d '{ "next": 1000 }' \ --user 'EMAIL:API_TOKEN' \ 'https://api.bitbucket.org/2.0/repositories/WORKSPACE/REPONAME/pipelines_config/build_number'

In the example above, you will need to replace:

• 1000 with the next desired build number

• EMAIL with your Atlassian account email address

• API_TOKEN with the API token you generated and copied in step 2

• WORKSPACE with the ID of your Bitbucket workspace

• REPONAME with the slug of your repository

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

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 the email address or the API token is invalid. Please ensure that you use your Atlassian account email address (instead of your Bitbucket username or the token name).

• Your credentials lack one or more required privilege scopes – you need to ensure your API token has the scope admin:pipeline:bitbucket.

• 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 API token name, not your Atlassian account email address.

Limitations

The build number can't be changed 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 lower than any existing build result in the repository. Since it is not currently possible to delete Pipeline builds, we must ensure the future build number will not clash with any existing build.