Script Roots

Script Roots are directories that ScriptRunner will automatically scan for scripts. The scripts you store here will be available across all of ScriptRunner.

Dependent classes are automatically detected and recompiled. The one exception is when you first change a dependent class without changing the class/script that’s actually called. However if you make a small change like adding a space to comment in the calling script, the changes to the base or dependent class trigger recompilation of both.

Set Up

When the ScriptRunner plugin is first installed, it creates a directory called Scripts under your Bitbucket home directory and then registers the directory as one of its script roots. This directory is sufficient for most users and no other configuration need be made. This is a logical place to store your scripts because it is preserved during Bitbucket upgrades, and it is accessible by all nodes in a clustered Bitbucket.

You can create subdirectories for your scripts. You could divide them into the business process they support. You could also create supporting or utility classes to be used by the subdirectories.

Make sure the supporting and utility classes have the correct package name or you will get a compilation error.

For example, a script and a class:


import util.Bollo log.debug ("Hello from the script") Bollo.sayHello()


package util public class Bollo { public static String sayHello() { "hello sailor!!!" } }

Absolute paths outside of script roots continue to work, but changes to dependent classes may not be detected.

Relative Paths

Relative paths are resolved to the script root until a file is found. If you want to use a path you had set up previously, you can add a script root that points to the working directory or to a place where your scripts were kept.


Let’s say that your Bitbucket instance is in /usr/opt/Bitbucket and your scripts are in /usr/opt/scripts, so you refer to them like this: ../scripts/foo.groovy.

When you implement script roots, you need a new property that points to your scripts directory, which would be set JAVA_OPTS=%JAVA_OPTS% -Dplugin.script.roots=/usr/opt/scripts.

Resolving ../scripts/foo.groovy relative to this script path has the same result.


  • If you have multiple roots, use a comma to delimit them.

  • If you work on a script locally before deploying to production, set breakpoints in scripts or classes and attach the debugger.

  • If you work on the ScriptRunner plugin, add the SRC and test directories from the checkout so you can work on the scripts without having to recompile.

    For example: set JAVA_OPTS=%JAVA_OPTS% -Dplugin.script.roots=checkout-directory\src\main\resources,checkout-directory\src\test\resources

On this page