Heads up! ScriptRunner for Bitbucket documentation has moved to https://docs.adaptavist.com/sr4bib. Adaptavist will keep this site up for a bit, but no future updates to documentation will be published here. ScriptRunner 6.20.0 will be the last release to link to scriptrunner.adaptavist.com for in-app help.

Some administration and housekeeping scripts are included in ScriptRunner for Bitbucket. You can find these under Administration > Built-In Scripts.

Built-In Scripts

Switch User

The Switch User built-in script allows administrator users to temporarily assume the identity of another user. Switch User has a variety of uses, such as:

  • Reproducing and troubleshooting problems specific to a user to diagnose permissions issues.

  • Updating an issue on behalf of another user if they are unavailable.

To switch back to your original user, click the Return to session as link in the Switch User banner.

switch user banner

Configuration Exporter

Use the Configuration Exporter built-in script to export extension configuration information to a descriptor (YAML) file. The YAML file contains information required to configure built-in extension points such as listeners, hooks, macros, and UI fragments, etc.

Using this file within Script Plugins when migrating from one instance to another, allows scripts to be automatically configured, saving time and ensuring consistency across instances.

  1. To create the YAML file, first navigate to Built-in Scripts > Configuration Exporter from ScriptRunner.

  2. Items with configurations available for export are shown in the Export What field. Select the items you wish to generate the YAML for. Multiple items can be exported to one YAML file.


    The Note field is used to distinguish one item from another, only items with notes are shown. Ensure the Note field has a value for all configuration items you wish to export.
  3. Click Run to generate the YAML snippet. Copy the snippet and paste it into your scriptrunner.yaml file.

    You can manually edit the code yourself to add more items, though it’s generally easier to re-generate the YAML file using the Configuration Exporter script.
For more information on using YAML files to create script plugins see Creating a Script Plugin.

Mirror Repositories

You can mirror repositories of a particular user or organization/group in GitHub, GitLab, and/or Bitbucket.

You can mirror repositories to ensure that you are not dependent on a remote version control service being available at all times and to continue your build and release process even in the event of a denial of service attack (or similar). You can read more about this here.

Each service has a unique way of naming a group of repositories:

  • Bitbucket Cloud — "team"

  • Bitbucket Server — "project"

  • GitLab — "project"

  • GitHub — "organisation"

When a remote repository is mirrored, the local repository mirror is kept up-to-date when changes are made to the remote repository. This happens in one of the following ways:

  • Installing a web hook into each remote repository. Then, the repository is updated when changes are pushed to the local Bitbucket repository.

  • Polling the remote repositories for changes every five minutes.

See the Step 4 of the Mirroring Repositories task below for more information.

Once the mirroring process has begun, you cannot push to the local Bitbucket repository. The remote repository is assumed to be authoritative and removes any branches in the Bitbucket repository that do not exist in the remote repository.

If the master branch is modified on both sides, synchronisation is broken. Remove the Bitbucket repository, and then rerun the setup.

A pre-receive hook is automatically setup for the mirrored repository to block all changes to the local Bitbucket repository.

If you want to push changes to the local Bitbucket repository, select the Remove option from View and Configure Mirrored Repositories.

Mirroring Repositories

  1. Enter the Organization/Team/Group/User.

  2. Enter a Target Project.

    Typically this is an empty project, but it doesn’t have to be. For this example, it is named "Mirror."

  3. To fill out API Key, follow authentication steps outlined below:

    Authentication is necessary, even if you are syncing public repositories, because of the rate limiting on unauthenticated accounts for remote APIs.
    • GitHub Authentication

      You need a GitHub API key so the plugin can list your repositories.

      If you do not already have one with at least the permissions shown in the image, you need to create one.

      1. Navigate to https://GitHub.com.

      2. Select Settings > Applications or click here.

      3. Under Personal Access Tokens select Generate New Token.

      4. Check that it has the correct permissions:

        create github token
    • GitLab Authentication

      You need to generate a GitLab personal access token so that ScriptRunner can authenticate with GitLab as your user.

      1. Navigate to https://GitLab.com.

      2. Select User Settings > Access Tokens.

      3. Configure the access token with a name and the scopes shown in the screenshot below:

        create gitlab token
    • Bitbucket Cloud/Server Authentication

      1. Enter the username and password of a user who is permissioned on the remote repositories.

  1. Select an option for How to Synchronise.

    • None

      If you select None, no synchronization is done.

    • Install Hook

      If you install a web hook, the remote service calls your Bitbucket instance whenever there are changes to the repositories, which prompts the plugin to sync the repositories. This is the preferred approach because changes are reflected almost immediately, and there is no unecessary polling.

      However, you can only use web hooks if your Bitbucket Server instance is accessible to the remote service over the internet.

    • Poll

      If you choose polling, each remote repository is polled every 5 minutes. This is a lightweight process, and is perfectly acceptable if you can’t use web hooks.

  2. Enter a Regular Expression to check against the repository name (not the part that appears in the URL), and can be used to filter the set of repositories you wish to mirror.

    To choose all, leave the default regular expression as is.

  3. Check the Sync New checkbox to sync new repositories that are created or forked into your team/organization/user automatically.

    If you have set a Regular Expression, it is respected when creating new mirrored repositories.

    New repositories are created in Bitbucket up to ten minutes after they appear in the remote service.

  4. Click Preview.

    If your token or credentials are correct, you should see a listing of the organisation/user repositories and if they are created or updated in the Bitbucket project.

    mirror preview
  5. Click Run.

    This can take a while, depending on the number and size of the repositories you are mirroring. You can tail the application log file to see progress, and use the View and Configure Mirrored Repositories function to see what has been created.

    You see the same screen when it finishes, but it now displays Exists for the local repositories.


If you are using web hooks for synchronisation, GitHub calls a REST endpoint in your Bitbucket instance when it’s pushed to. To know that it’s GitHub that’s calling, the payload of the call is hashed with a secret token that you supply.

Follow these steps to generate a random token:

  1. Run this code in Script Console.

    import java.security.SecureRandom
    SecureRandom random = new SecureRandom();
    String str = new BigInteger(130, random).toString(32);
  2. Restart Bitbucket with the property -Dgithub.secret.token=<from above>.

    from above is where you add the generated code.

If you already have remote repositories that are synced by web hooks, you need to update these hooks, by rerunning this script.

If you do not have direct access to the internet, the web services calls respect your values of http.proxyHost and http.proxyPort. However, you must change your .gitconfig on the Bitbucket server to specify the proxy.

There is useful information here on how to set a proxy only for certain sites: http://stackoverflow.com/questions/16067534/only-use-a-proxy-for-certain-git-urls-domains. Currently, authenticated proxy access is not supported.

View and Configure Mirrored Repositories

You can view the status of your mirrored repositories and projects, and you can modify the remote sync options.

You can check whether your Bitbucket repository is up to date with the remote repository by clicking the Check or Check All links.

A warning icon means repositores are not in sync. They do not mean that there is necessarily a problem. Warning icons should not appear if you are using a web hook trigger. If you are using polling, warnings catch up on the next scheduled task (every 5 minutes). If a repository is persistently out of sync, check the application log file.

A warning icon is also displayed if the repository is empty or unavailable. Bitbucket and GitHub provide us with no option to distinguish between those two cases.

If you previously set that repositories are automatically created, the projects set to do that are listed below the repositories. If you wish to stop this, check the checkbox under Stop Synchronization, and then click Run.

To change the regular expression, stop synchronization as above, and then recreate the configuration. It’s fine to mirror into existing repositories, and this should not take very long.

configure mirrored repos
configure mirrored projects

Clone Repository Configuration

This clones the configuration of an existing repository to a new empty repository.

In Bitbucket 5.2.0+ if the existing repository inherits particular configuration items from the project then the Target Project Settings are inherited for the cloned repository.

You can set up one or more template repositories, and then clone them when creating new repositories, in order to ensure the correct settings for hooks and pull requests etc.

The following configuration items are replicated in the new repository:

  • Repository permissions, including whether the source repository is publicly accessible and forkable

  • Branch permissions

  • Enabled hooks settings

  • Branch model

    This is of limited utility as some settings in the branch model cannot be set until the branch exists, such as the production branch
  • Pull request settings (those that are shipped with Bitbucket)

    • Minimum number of approvals

    • Require all tasks to be resolved (useful in conjunction with adding default tasks to new pull requests)

    • Minimum number of successful builds

    • Require all reviewers to approve the pull request (Bitbucket Server 4.9+ only)

    • Enabled merge strategies and default merge strategy (Bitbucket Server 4.9+ only)

  • ScriptRunner features

    • Pre hooks

    • Post hooks

    • Merge checks

    • Listeners

Repository Size Report

This generates a report of your repository sizes.

The report can be run from the Administration > Built-In Scripts or Project Settings > Built-In Scripts. Here’s an example of the type of report you’ll see generated:


You can either view the report after running the script or export the report as a CSV file.

View And Delete Orphaned Personal Repositories

Bitbucket users can create personal repositories that belong to the user who creates them and are not easily visible to Bitbucket administrators.

When a Bitbucket user is deleted in a local user directory or made inactive in an external user directory, their personal repositories remain within Bitbucket and are still accessible if the administrator knows the URL for the repository.

Bitbucket does not currently offer a convenient way for an administrator to view or delete all personal repositories that no longer have an owner (orphaned).

View and Delete Orphaned Personal Repositories lists all orphaned repositories and optionally allows an administrator to delete the orphaned repositories.

Here is an example showing a list of orphaned repositories from users that have been deleted:


In the Repository column, there are links to each orphaned repository, and the administrator can click these links to browse to the orphaned repository. Once you are within Repository Settings, the repository can then be deleted.

If the administrator wants to bulk delete all orphaned repositories, they can do so by checking the Delete Orphaned Repositories? checkbox, and then pressing Run.

List Scheduled Jobs

Use the List Scheduled Jobs built-in script to view details of all scheduled jobs on the current instance.

Results show the Job ID, Interval, Next Run, and Run Mode of each job, listed below the feature under which they run.

To use this script, you need to click Run.

View Server Log Files

Use View Server Log Files to see the last N number of lines of the desired server log.

This built-in script allows users to check log files without the need to connect to and have access to the server.

Clear Groovy Class Loader

Use Clear Groovy Caches to manually clear caches if automated clearing fails. Automation should reload classes whenever a script is modified; however, dependent classes can fail to reload.

There are no fields for this built-in script. You just have to select Run or Preview. After you run this script, expect a delay in screen refresh because classes are recompiled when clearing caches.

Example Scenario

If you have a custom class file (ClassA) in your script roots and another Groovy script imports that file, modifications to ClassA may not show up until you modify the script that imports them or clear the Groovy cache with this script.

Have questions? Visit the Atlassian Community to connect, share, and learn with other Atlassian users and experts, including Adaptavist staff.

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

Want to learn more? Check out courses on Adaptavist Learn, an online platform to onboard and train new users for Atlassian solutions.