Be able to set an initial value for the BITBUCKET_BUILD_NUMBER variable

Issue #14606 resolved
Peter Havenga created an issue

I'm moving from another build mechanism to Bitbucket pipelines. I need my builds to have a build nr > 600. I currently do not see any method to set the BITBUCKET_BUILD_NUMBER to start at this number and think that such a feature would be a good addition.

Comments (7)

  1. Matt Ryall

    We actually built this as a feature of build numbers, and have support for setting an initial value via the Bitbucket REST API. But I'm not sure it's working correctly yet.

    The idea is that you can send a PUT with the correct payload to the API documented here:

    However, I'm just checking with the dev team on exactly how to get it to work. I get a permission failure when I tried to PUT to the API URL just now.

    We don't have plans to offer a UI for this at the moment because it will be such a rarely accessed operation.

    I'll keep this ticket open until we find out a way to get this working for you. Stay tuned!

  2. Matt Ryall

    Okay, here's how you do it:

    1. Log in to Bitbucket and go to your Bitbucket settings > App passwords via the user menu. You need to create a new app password with permission to "edit variables" in Pipelines. Grab that password on your clipboard.
    2. Use curl to PUT to the Pipelines build_number config API:
    curl -H 'Content-Type: application/json' -XPUT \
      -d '{ "next": 1000 }' \
      --user 'USERNAME:PASSWORD' \

    From this example, replace 1000 with your desired build number (which must be higher than the most recent build number), USERNAME (both instances) with your Bitbucket username, REPONAME with your repository slug, and PASSWORD with the app password you generated above.

    If it worked correctly, you'll get the following result back from curl:

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

    Here are the error messages I saw while testing and what they mean:

    • 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.
    • The request body contains invalid properties - your build number is lower than existing builds in Pipelines.

    Hope this helps!

  3. Log in to comment