Upgrading To Bitbucket Server 4.0
This page describes how to migrate from Stash to Bitbucket Server 4.0. Release 4.1.2 is the first release that is compatible with Bitbucket Server.
Bitbucket Server is the next evolution of Stash, however Atlassian have taken it as an opportunity to bypass their usual API stability policy. As such, you will have to modify your scripts. Atlassian have intimated that this is a one-time change, and after this there will be several years of low friction in the API. If you don’t have any custom scripts, and are only using the simple conditions that come as examples in the plugin, you may well have nothing to do.
If you have any issues please contact us via our Service Desk.
This page is split up into a suggested upgrade procedure, and the possible areas you will need to change.
At the time of writing, the official page explaining the upgrade procedure is here, although there is currently permissioning on this page.
How to upgrade
First you should create a clone of your production system that you can do a practice upgrade on. Creating staging systems is not well documented, but there is enough information in STASH-5271 and on this answer.
Once you have the staging system created, upgrade it to Bitbucket Server 4. Then install the ScriptRunner plugin.
The static type checker that was recently introducted to _ScriptRunner for JIRA_ is now available in ScriptRunner for Bitbucket Server, so you should be able to see quite quickly if you have any problems.
You should open each admin page that lists each extension point, eg pre-receive hooks, event handlers etc. Look for code highlighted with red errors, and fix them
The condition script is not currently shown in the overview page, so click edit for each event handler or hook etc, and check that the condition shows the green dot of successful compilation.
If practical, test your most important scripts and conditions in your staging server.
Finally, make sure that your maintenance window includes enough time to do your production upgrade, and then the modifications to the scripts that you have already tested in your staging server.
Areas of change
This is not a definitive list, for that see the Atlassian guidelines. However, these are the changes I think you are most likely to have to make.
Packages have been renamed from
com.atlassian.bitbucket. This will affect you if you have custom scripts, or conditions, that import any classes.
If there are errors in your scripts you will see something like:
You can correct that in this case by just replacing the word
Some event classes have changed package too, for example
com.atlassian.stash.event.RepositoryCreatedEvent has moved to
com.atlassian.bitbucket.event.repository.RepositoryCreatedEvent, that is, it’s moved under the
repository package. Same for project events
Another example. If you were using the condition to check a user was in a group, it may have been:
import com.atlassian.sal.api.component.ComponentLocator import com.atlassian.stash.user.UserService import com.atlassian.stash.user.StashAuthenticationContext def userService = ComponentLocator.getComponent(UserService) def authContext = ComponentLocator.getComponent(StashAuthenticationContext) userService.isUserInGroup(authContext.getCurrentUser(), "project-creators")
Now it should be:
import com.atlassian.sal.api.component.ComponentLocator import com.atlassian.bitbucket.user.UserService import com.atlassian.bitbucket.auth.AuthenticationContext def userService = ComponentLocator.getComponent(UserService) def authContext = ComponentLocator.getComponent(AuthenticationContext) userService.isUserInGroup(authContext.getCurrentUser(), "project-creators")
Some classes have changed names, for example
RepositoryMetadataService has become
StashUser is now
KeyedMessage behaviour change
com.atlassian.bitbucket.i18n.KeyedMessage is used to cancel events in event handlers. The signature is
KeyedMessage(String key, String localisedMessage, String rootMessage).
The first parameter is the key, which is used for translating the messages into different languages. Typically in scripts you do not bother with localisation, so previously you may have written:
event.cancel(new KeyedMessage(null, "some message", null)
Now all parameters are mandatory, so I suggest you use:
def msg = "some message" event.cancel(new KeyedMessage("dummy", msg, msg)
Have questions? Visit the Atlassian Community to connect, share, and learn with other Atlassian users and experts, including Adaptavist staff.
Want to learn more? Check out courses on Adaptavist Learn, an online platform to onboard and train new users for Atlassian solutions.