Some administration and house-keeping scripts are included, and can be found under Admin → Built-In Scripts.

Built-in Scripts

Switch User

This allows you to temporarily assume the identity of another user. You can use this for example to:

  • reproduce a problem a user is telling you they are having, e.g. diagnose a permissions problem

  • merge a pull request on behalf of another user (Bitbucket)

  • Update an issue on behalf of another user (if they are unavailable) (JIRA)

To use, enter the user ID of the user you wish to become, and press Run. To return to yourself, log out, then log in again.

When this script is used, it will generate a log entry in the audit log like so:

switch user audit log
You cannot su from a user having only administrative rights to a system administrator.

Mirror GitHub or BitBucket User, Team or Organization

This is used to mirror all the repositories of a particular user or organization in GitHub or BitBucket.

Mirroring repositories can be useful to ensure that you are not dependent on GitHub.com or bitbucket.org 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…​ GitHub uses the term organization and BitBucket uses the term team - both of them are analagous with a user, and are just a way of grouping repositories.

In the case of either BitBucket or GitHub, once it has cloned the repositories to your Bitbucket project, it will keep them up to date when further 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 the 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/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.

BitBucket 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, GitHub or BitBucket 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 GitHub or BitBucket (Cloud).

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 organization/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 - only for 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)

List scheduled jobs

This script lists the job runners and the job IDs that are scheduled in your instance. If the job has parameters then these are shown in the box below.

No parameters are required for this script, just click Run.

View server log files

Simply shows the last lines of the desired server log. This is useful for quickly checking the log files without having to connect to your server and find the log file, especially if you haven’t been given access to the server.

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.