ScriptRunner supports looking up its script roots from inside another plugin. In other words, it can automatically add the root of another plugin to its collection of script roots. Built-in scripts (admin scripts, but also hooks, listeners etc) are loaded from the script roots.

ScriptRunner also supports storing the configuration of your scripts as code. You can bundle a configuration file into your plugin that details the configuration for a Script Listener, REST Endpoint, Script Fragment, or other configured script so that as soon as the plugin is installed, your script is automatically configured. In Jira, you should also be able to provide someone a workflow, which references scripts like com/atlassianexpert/acme/custy/Foo.groovy, and ship these files in a plugin.

This can be useful for Atlassian Experts and partners who would like to deliver a fully functional business process to a customer, without them having to copy scripts to their server. It can also help teams that make heavy use of ScriptRunner to customize their Atlassian applications implement software development practices for their script code, including version control, automated testing, code review, and continuous integration as they have need.

ScriptRunner will detect the plugin and automatically add it to its list of script roots, and install the listeners, macros etc. Upon disabling or removing the script plugin these items will also be removed.

Creating a Script Plugin

The first step is to open one of the samples as discussed in setting up a development environment. Ensure that you are able to follow all the instructions on that page before continuing.

Fork that repository and start working in the relevant product-specific sub-directory, or copy the pom to a new directory.

Start Work

You can either add plain scripts or "built-in scripts" which can be parameterised. Such scripts must implement the com.onresolve.scriptrunner.canned.CannedScript interface, and must be added to specific packages in order to show up in the correct place in the UI. To add scripts to the Built-in Scripts menu, add them to the com.onresolve.scriptrunner.canned.common.admin menu.

See the sample plugin source code for further examples.

ScriptRunner YAML File

You can include a special scriptrunner.yaml file that contains details of configured listeners, macros, hooks, UI fragments etc.

The scriptrunner.yaml file should be at the root of the jar file (put it in src/main/resources in your source project), if present at all.

It contains the information required to configure the built-in extension points such as listeners, hooks, macros etc.

To create it, use Admin → Built-in Scripts → Configuration Exporter. Select the items that you wish to generate the YAML for.

In order to disambiguate one item from another the note field is used, and only those items with notes are shown. So make sure any configuration item you want to export has a value in the note field.

The exporter may look like this:


On clicking Run the YAML snippet will be generated. Paste it in to your script-runner.yaml file. You can manually edit the code yourself, though it’s generally easier to re-generate the YAML file using the Configuration Exporter script.

Maven Goals

If you have modified compiled code or the YAML configuration file, you will need to reinstall the script plugin. Run mvn package. Quick Reload should notice the updated jar and install the plugin.

If you have disabled Quick Reload, use mvn package jira:install (or confluence:install, bitbucket:install, bamboo:install as appropriate).

Running mvn package will create a plugin jar that you can install like any other plugin. This will be in the target directory.


Running mvn integration-test will run the application, and then execute any tests you have written, inside of the application.

Known limitations

There are some limitations with creating a Script Plugin. Please give us feedback as this is a new feature.

  • If you disable or uninstall ScriptRunner, your script plugin will be disabled. It won’t be enabled automatically when you re-enable ScriptRunner.

  • Certain scripts cannot be created or configured via the scriptrunner.yaml file, such as Scripted Fields in ScriptRunner for Jira. The sample plugin contain an example of how to work around this (by creating a Scripted Filed in an upgrade task).

For how-to questions please ask on Atlassian Answers where there is a very active community. Adaptavist staff are also likely to respond there.

Ask a question about ScriptRunner for JIRA, for for Bitbucket Server, or for Confluence.