Release 4.x

Check out what's new for ScriptRunner for Bitbucket. 


  • Released 28 March 2017.


Export to CSV in Repository Size Report

You can now export the repository size report as a CSV file. This is useful if you want to share the report with others or running the report times out due to a large number of projects and repositories.

Templated JQL Clause in Require Commits to be Associated with a Jira Issue

It’s now possible to use values in the binding to build your JQL clause.

Please see the documentation here for an example of matching against a fix version before merging.

New Features

  • [SRBITB-186] - Ability to export data to CSV in repository size report
  • [SRBITB-206] - Require valid Jira issue merge check build JQL clause dynamically using the pull request


  • Released 19 Jan 2017.


This release was mainly to improve performance of the enforce trusted commit authors pre-receive hook when excluding branches and tags.

Trusted Commit Authors Performance

Previously we would list all the excluded branches and tags when reading commits in the enforce trusted commit authors pre-receive hook to skip merged and rebased commits as they were assumed to have already been verified by the hook. This meant the hook would timeout if there were many thousands of tags and branches for a repository.

Instead of listing the exclusions we now check each commit pushed against the commit index to check if it exists elsewhere in the repository. The commit index should generally be up to date in most cases.

If you are seeing issues with the hook rejecting merged or rebased commits and only succeeding after retrying the push a number of times you should carefully look at adjusting the commit index properties which can be found here. This will allow the pushed commits to be reindexed more quickly, although it will consume more resources from the server.

Bug Fixes

  • [SRBITB-191] - Trusted commit authors hook timeout when there are a large number of tags


  • Released 16 Dec 2016.

This release was mainly for compatibility with Bitbucket Server 4.12.0.


Default Script Roots for Data Center

When using the default script roots <bitbucket-home>/scripts in data center we would look up scripts from the local home. This was wrong and in this release we now look up the scripts from the shared home.

Previously this meant you would need the scripts in the local home for each node. Now the scripts just need to be under the shared home.

Bug Fixes

  • [SRBITB-176] - Merged commits from a tag into a branch is rejected by the trusted commit authors hook
  • [SRBITB-181] - Auto add approvers listener fails to add reviewers when pull request updated on Bitbucket 4.9+
  • [SRBITB-183] - Add additional diagnostics to auto add approvers
  • [SRBITB-185] - Compatibility with Bitbucket Server 4.12
  • [SRJIRA-2090] - "View server log file" fails for Jira Data Center


  • Released 22 Nov 2016.

New Features

Upgrading to Bitbucket Server 4.11.0

Bitbucket Server 4.11.0 is not supported due to a bug being introduced by Atlassian, please see BSERV-9327 for more details of this. However we support 4.11.1 onwards.

This prevents the plugin from starting up and you will see a java.lang.NoClassDefFoundError exception in the logs. There is not a sensible workaround for this so we are not supporting it.

The Marketplace does not allow us to specify two version ranges so you will see that it is supported when it really isn’t.

You should upgrade from 4.11.0 to 4.11.1 if you want to continue using ScriptRunner.

Removing Mirroring on Mirrored Repositories

The ability to remove the mirroring on repositories setup using the mirroring feature was added in this release. This means a user will be able to remove the mirror and push to the local repository if the remove option is selected.

Please see mirroring for more details on this.


pathsMatch for Pull Requests

Previously when using pathsMatch against a pull request we matched against the commits. We have now changed this default behavior to match against the pull request changes in the diff instead.

To see how to use pathsMatch on commits for the old behavior please read this section.

Bug Fixes

  • [SRBITB-165] - Use standard in option for piping refs to git rev-list when reading raw commits
  • [SRBITB-168] - Fix paths match for pull request create screen to handle merging and rebasing correctly
  • [SRBITB-171] - Allow commits from fork option in trusted commit authors hook not excluding commits on fork
  • [SRBITB-172] - Paths match not matching full paths for pull request changes
  • [SRBITB-177] - Non-system admins can't view repository level event handlers sometimes
  • [SRBITB-179] - Branch and tag naming enforcement per repository listener does not fire correctly


  • Released 10 Oct 2016.

This release was mainly for compatibility with Bitbucket Server 4.10.

Bug Fixes

  • [SRBITB-157] - Compatibility with Bitbucket Server 4.10
  • [SRBITB-159] - Clone repository built-in script not copying pull request build settings


  • Released 28 Sept 2016.


Script Plugins

Script Plugins have been reworked, and now support including a special descriptor file, so that you can ship a script plugin which contains configured script fragments, rest endpoints, listeners etc.

In addition, we have reworked the documentation for setting up a development environment, and published some sample maven projects that should get you up and running with a development environment very quickly.

Naming Standard Enforcement Event Handler

The naming standard enforcement pre-receive hook only blocks branch and tag names when a user does a git push of a new branch or tag. The new naming standard enforcement event handler blocks branch and tag names created through the Bitbucket user interface.

Trusted Commit Authors Diagnostics

The enforce trusted commit authors pre-receive hook will now show you why certain commits were blocked in the hook message and provide you with the name and email address of the current user. So users can quickly see why their commits were blocked.

Enforce Trusted Commit Authors Match Name

Previously the enforce trusted commit authors pre-receive hook match name option matched on Bitbucket username. This wasn’t as useful as using the display name which is most likely what the .gitconfig contains for the user, so we now match commits against display name and dropped support for username.

Bug Fixes

  • [SRBITB-109] - pathsMatch fails when paths contain octal escapes for non-ascii unicode chars
  • [SRBITB-125] - Better validation on mirroring username
  • [SRBITB-130] - Pushing tags and pushing after fast-forward merge with trusted commit authors hook blocks push
  • [SRBITB-133] - Web items trigger dialog not working for repository actions
  • [SRBITB-141] - Max file size hook missing commits
  • [SRBITB-143] - Merge BBS default reviewers with reviewers from auto add approvers listener
  • [SRBITB-146] - Custom web item to trigger dialog should reuse existing dialog or remove the current dialog on close
  • [SRBITB-149] - Cannot remove event listener and extant event listeners don't get listed
  • [SRBITB-151] - Block out of date pull requests fails when no common base found between branches
  • [SRBITB-65] - State in hook error message why enforce trusted commit authors hook rejected commits
  • [SRBITB-122] - Check Commit name as well as Author name in trusted commit authors pre hook
  • [SRBITB-134] - Scripted event handler for branch and tag name enforcement
  • [SRBITB-46] - Github and bitbucket mirror - check sync status doesn't work if the source repo is empty


  • Released 29 June 2016.

Bug Fixes

  • [SRBITB-123] - Document commits must match name option for trusted commit authors pre-hook
  • [SRBITB-128] - "default project permissions" with default level of No Access causes exception
  • [SRBITB-129] - cannot switch user when username contains an @ or several other characters
  • [SRBITB-131] - Make ScriptRunner compatible with BBS 4.7.1


  • Released 29 May 2016.

Bug Fixes

  • [SRBITB-87] - Bitbucket links broken in documentation
  • [SRBITB-111] - Ignore deleted files in protect git refs condition


  • Released 19 April 2016.

New Features

Web Fragments

Web fragments allow you to customize the user interface using simple scripts…​ the possibilities are endless. This replaces the original method for customizing the UI here (which will continue to work).

The documentation does not have worked examples for Bitbucket yet, but the techniques are the same as in Jira web fragments.

  • Released 29 March 2015.

These links are not accessible externally. We are working on making them accessible.

Bug Fixes

  • [SRSTASH-84] - Documentation - documented delete branch on auto merge
  • [SRSTASH-97] - Fixed max file size hook when pushing new empty branches
  • [SRBITB-5] - Fixed endless looping over change sets when retrieving commits

  • Released 29 March 2015.

Bug Fixes

  • [SRSTASH-91] - Documentation - a few SR Bitbucket links have likely changed
  • [SRSTASH-93] - RequireValidJiraIssue does not examine only new commits
  • [SRSTASH-68] - Add the ability to fire an event when a mirrored repository refs change
  • [SRSTASH-84] - Auto merge of PR should have the option to delete the branch
  • [SRSTASH-87] - match names as well as emails in enforce trusted commits
  • [SRSTASH-88] - auto sync - set default to merge and override and alert if problems
  • [SRSTASH-10] - listeners don't handle subclasses of the configured event

  • Released 02 March 2015.

New Features

This page describes how to upgrade to release 4.1.2. This 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 introduced 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.

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

Package Names

Packages have been renamed from com.atlassian.stash to 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 stash with bitbucket.

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")

Class Names

Some classes have changed names, for example RepositoryMetadataService has become RefService. StashUser is now BitbucketUser.

KeyedMessage Behavior 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)

On this page