Getting Started

Stash Extension Points


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

Built-in Scripts

Switch to a different user

This allows you to temporarily assume the identity of another Stash 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

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.

Mirror GitHub or BitBucker 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 or 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 Stash 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 Stash.

  • polling the remote repositories for changes every five minutes

Once the mirroring process has begun you cannot push to the local Stash repository. The remote repository is assumed to be authoritative and will remove any branches in the Stash 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 Stash repository and rerun the setup.

You can use the protect references pre-receive hook to block all changes to the local Stash repository.


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, 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.


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 Stash 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 Stash instance is accessible to GitHub or BitBucket.

If your Stash is not accessible to the internet then you could run ngrok, or open your firewall to requests from 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 Stash 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 Stash 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.


If you are using web hooks for synchronisation, GitHub will call a REST endpoint in your Stash 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.


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

Then take this number, and restart Stash 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 Stash server to specify the proxy. There is useful information here on how to set a proxy only for certain sites: 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 Stash 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.

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. 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 Stash, which are currently:

List scheduled jobs

This script lists the job runners and the job IDs that are scheduled in your Stash 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.