Upgrade to Bitbucket 9

Compatibility with Bitbucket 9

Only those versions marked as compatible in the Atlassian Marketplace will work with Bitbucket 9. If you have been through the Bitbucket 7 to Bitbucket 8 upgrade, this process should be familiar and relatively smooth. For further information on Bitbucket 9 see Atlassian's release notes. The information on this page is focused on the areas of change likely to affect your scripts.

Script functionality

Some of your scripts may fail if you upgrade without modifications. The major areas of change are listed below and on the breaking changes page.

Breaking changes

There are some key breaking changes you should be aware of when upgrading to Bitbucket 9 for:

Raw XML Module Breaking Change for Bitbucket 9
Web Panel Breaking Change/Deprecation for Bitbucket 9
Web Resource Breaking Change for Bitbucket 9
Gray APIs have been removed along with other API changes
JDK has been updated. The minimum supported version of the JDK is now JDK 17.

Full details of the changes related to this upgrade are provided in Breaking Changes.

Upgrading your instance

Note: We recommend you also read the Bitbucket Data Center upgrade guide.

If you do not have a staging environment, we recommend you invest the time into creating one. You should be able to reliably clone your production instance to the staging environment, so you can test plugins and upgrades.

We recommend you use the following strategy when upgrading your instance:

Make changes to remove all deprecated code before you upgrade. If you remove deprecated code, then your code has the best chance of working unchanged with Bitbucket 9.
Note: Deprecated code shows as a warning.
Make sure your staging instance is up to date with your production instance.
Upgrade your staging instance to Bitbucket 9.
Review your scripts to make sure you don't have any type-checking errors and Test.
Record any changes if needed.
Once you're happy with your staging instance you can upgrade your production instance and apply any recorded changes.

Note: When upgrading your production instance that contains inline scripts, manual adjustments are required where necessary. To update script files, you can modify your Scripts Directory, typically by merging changes from a branch.

Changes to Bitbucket API

You can review changes to the Bitbucket API on Atlassian's API Changelog page.

Anything else?

Did we miss something important that script authors should take into account when upgrading? Please let us know.

If it's likely to affect more than a couple of users we will add it to this documentation.