Upgrade to Bitbucket Server 5.0

This page describes how to migrate from Bitbucket Server 4.x to 5.0. Release 5.0.5 is the first release that is compatible with Bitbucket Server 5.0 onwards.

Atlassian have removed a number of deprecated methods and provided alternatives, therefore you will have to modify your scripts. 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 which we recommend you read before upgrading.

How to Upgrade

First you should create a clone of your production system that you can do a practice upgrade on. There is an Atlassian knowledge base article about creating a staging system here.

Once you have the staging system created, upgrade it to Bitbucket Server 5. Then install the ScriptRunner plugin.

The static type checker available in ScriptRunner for Bitbucket Server should be able to indicate problems quite quickly.

You should open each admin page that lists each extension point, eg pre-receive hooks, listeners 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 listener or hook etc, and check that the condition shows the green dot of successful compilation.

Test

If practical, test your most important scripts and conditions in your staging server.

Production Upgrade

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 we think you are most likely to have to make to your scripts.

Deprecated APIs removed

APIs that were marked as deprecated in Bitbucket Server 4 have now been removed. Full details of which classes, interfaces and methods have been removed can be found here.

Therefore you may need to update your custom scripts and conditions. You should be able to find the existing class, interface or method here and use the alternative listed in those Javadocs.

Comment API

Previously you had to use com.atlassian.bitbucket.commit.CommitService or com.atlassian.bitbucket.pull.PullRequestService to add comments. Bitbucket Server 5 introduces a new centralized comment API instead for making comments.

For example to add a comment to a pull request you can use the following code:

 
import com.atlassian.bitbucket.comment.AddCommentRequest
import com.atlassian.bitbucket.comment.CommentService
import com.atlassian.sal.api.component.ComponentLocator

def commentService = ComponentLocator.getComponent(CommentService)

def addCommentRequest = new AddCommentRequest.Builder(pullRequest, "a comment").build()

def comment = commentService.addComment(addCommentRequest)

You can view the full details of this change here.

If you add/remove or read comments you’ll likely have to make these changes to your scripts.

Condition Examples

We have updated the condition examples we provide to you in ScriptRunner in the Expand Examples section and have provided some extra methods that Atlassian have removed to ease the upgrade process if you’ve previously used one of these examples. For example com.atlassian.bitbucket.repository.RefChange.getRefId is provided.

You may still find that you need to update your condition if it’s something other than the examples, uses other deprecated APIs or involves retrieving comments.

On this page