Some administration and house-keeping scripts are included, and can be found under Admin → 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 the original user, log out and log in again.

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.

    config-exporter

    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 GitHub/GitLab/Bitbucket Repositories

This is used to mirror all the repositories of a particular user or organisation/group in GitHub/GitLab/Bitbucket.

Mirroring repositories can be useful to ensure that you are not dependent on a remote version control service being available at all times, and that you can always 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.

A note on nomenclature, each service has a unique way of describing a group of repositories. Bitbucket Cloud uses the term team and Bitbucket server uses the term project. GitLab uses the term project, and GitHub uses the term organisation.

When a remote repository has been mirrored, the local repository mirror will be kept up to date when changes are made to the remote repository. This will happen either:

  • Through installing a web hook into each remote repository, such that when they are updated when changes are pushed to Bitbucket.

  • Polling the remote repositories for changes every five minutes.

Once the mirroring process has begun you cannot push to the local Bitbucket repository. The remote repository is assumed to be authoritative and will remove any branches in the Bitbucket repository that do not exist in the remote. If the master branch is modified on both sides then synchronisation will be broken, and you should remove the Bitbucket repository and 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 then you should select the Remove option from the configure mirrored repositories built-in script.

Usage

Enter the Organization/Team/Group/User, and a target project. Typically this will be an empty project called for instance Mirror, but doesn’t have to be.

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

GitHub Authentication

You will need a GitHub API key so that the plugin can list your repositories. If you do not already have one with at least the permissions shown below, you need to create one. To do that, in GitHub.com, go to Settings → Applications or click here. Under Personal access tokens click Generate new token. It should have the following permissions:

create github token

Enter your API key.

GitLab Authentication

You will need to generate a GitLab personal access token so that ScriptRunner can authenticate with GitLab as your user. A personal access token can be generated by browsing to User Settings → Access Tokens. On the access tokens page, configure the access token with a name and the scopes shown in the screenshot below:

create gitlab token
Bitbucket Cloud/Server Authentication

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

Synchronisation

You have the choice of keeping your repositories in sync either by telling the plugin to install a remote web hook, or by polling.

If you have it install a web hook, the remote service will call your Bitbucket instance whenever there are changes to the repositories, which will prompt 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 it if your Bitbucket Server instance is accessible to the remote service over the internet.

If your Bitbucket is not accessible to the internet then you could run ngrok, or open your firewall to requests from github.com. If you use ngrok or similar you will need to modify the web hook URL in each GitHub repository.

If this is not an option then each remote will be polled every 5 minutes. This is a lightweight process, and is perfectly acceptable if you can’t use web hooks.

If you select None, no synchronization will be done.

Regular Expression

The regular expression is done 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.

New repositories

It can be useful to have new repositories that are created or forked into your Team/Organization/User automatically. To have this happen, check the Sync new checkbox.

If you have set a regular expression above, that will be respected when creating new mirrored repositories.

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

Finally, click Preview. If your token or credentials are correct you should see a listing of the organisation/user repositories, and whether they will be created or updated in the Bitbucket project:

mirror preview

Now 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 Configure Mirrored Repositories function to see what has been created.

On completion you will see the same screen, although now it will say EXISTS for the local repositories.

Security

If you are using web hooks for synchronisation, GitHub will call a REST endpoint in your Bitbucket instance when it’s pushed to. To know that it’s GitHub that’s calling you, the payload of the call is hashed with a secret token that you supply. You can generate a random token by running the following in the Script Console.

import java.security.SecureRandom

SecureRandom random = new SecureRandom();
String str = new BigInteger(130, random).toString(32);

Then take this number, and restart Bitbucket with the property -Dgithub.secret.token=<from above>. If you already have remote repositories that are synced by web hooks, you will need to update these hooks, by rerunning this script.

If you do not have direct access to the internet, the web services calls will 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.

Configure Mirrored Repositories

This function allows you to view status of your mirrored repositories and projects, and modify the remote sync options.

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

A warning icon just means they are not in sync, not that there is a problem necessarily. This should not happen if you are using a web hook trigger - if you are using polling it will 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 will also be displayed if the repository is empty or unavailable. Bitbucket and GitHub provide us with no option to distinguish between those two cases.

If you have previously set it up so that new repositories are automatically created, the projects where you have done that are listed below the repositories. If you wish to stop this, check the checkbox under Stop synchronization, and click Run.

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

configure mirrored repos
configure mirrored projects

Clone Repository

This will clone 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 will be inherited for the cloned repository.

You can set up one or more template repositories, and 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 - although 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, which are currently:

    • 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 pre hooks, post hooks, merge checks and event handlers

Repository Size Report

This will generate a report of your repository sizes.

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

thumb
thumb

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

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.

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.

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.