Set up Bitbucket Smart Mirroring

Smart Mirroring for Bitbucket Cloud is a Premium feature. Upgrade your account to a Premium plan to get the full functionality with your Smart Mirror.

Learn more about Bitbucket Premium.

Smart Mirroring for Bitbucket Cloud uses a local install of Bitbucket Server (that you host) to mirror your repositories hosted in Bitbucket Cloud. Read more about Smart Mirroring for Bitbucket Cloud.

This page describes how to set up Smart Mirroring, using a valid SSL certificate:

1. Install Bitbucket Server on the mirror

The easy way to install a mirror is to download and run the Bitbucket installer, using the Install a new mirror option. (Note that the same distribution is used to install Bitbucket Server, Bitbucket Data Center and mirror instances connected to either Bitbucket Cloud or Bitbucket Data Center.) 

  1. Go to and download the latest version of the Bitbucket installer to the server where the mirror will run. Make sure that:

    • you select one of the version from Bitbucket Server 4.10.2 to 6.5.

    • the server machine runs Linux – you can evaluate a mirror on MacOS but we currently don't support Windows.

    • the server machine meets the other requirements for Bitbucket Server – see the Supported platforms for detailed requirements, including those for Java and Git.

    • the server machine is well-provisioned – the mirror needs to be provisioned with enough CPU, memory, and I/O resources to handle peak workloads. See Scaling Bitbucket Server for more information.

  2. Run the installer, making sure to select Install a new instance and then Install a mirror instance.

  3. Complete the rest of the installation wizard.

Install from an archive file...

Alternatively, If you prefer not to use the Bitbucket installer, you can:

  1. Install Bitbucket Server from an archive file but do not start it (you'll need to configure SSL, described in step 2 below, before starting the mirror).

  2. Add the following line to your ${BITBUCKET_HOME}/shared/

    1 application.mode=mirror

2. Set up HTTPS on the mirror

You must configure your mirror to use HTTPS with a valid SSL certificate, and make secure access mandatory. The SSL certificate must be signed by a Certificate Authority, be anchored to the root, and not have expired. The mirror setup wizard, which runs when you first start the mirror, will not proceed if the mirror does not have a valid SSL certificate. You cannot use a self-signed certificate. SSL certificates are issued by a trusted third-party Certificate Authority (CA), such as VeriSignDigiCert or Thawte. Atlassian does not provide SSL certificates.  

For performance and security reasons, we strongly recommend that you:

  • run the mirror behind a reverse proxy such as Apache, nginx or HAproxy

  • terminate SSL at the proxy

See one of the options in Securing a reverse proxy using HTTPS for more information about how to do this, and how to configure the mirror to use your SSL certificate.

3. Start the mirror

Change directory in a terminal to the <Bitbucket Server installation directory> and run:

1 bin/

See Starting and stopping Bitbucket Server for more information on starting and stopping mirrors.

4. Set up the mirror

Once your mirror has started, navigate to https://<mirror-full-name>  in your browser, where  <mirror-full-name>  is your mirror's fully qualified DNS name which you set up in Step 2. You'll see the Bitbucket Server setup wizard. The  <mirror-full-name>  will be pre-filled as the Mirror base URL

Mirror name

The human-readable name of the instance. Users will see this name when selecting a mirror to clone from.
Choose a name that your users will recognize as the fastest one for them.

Mirror base URL

The URL where the mirror can be accessed.

Primary server location

Select Bitbucket Cloud.

Before you click Submit configuration, make sure that Bitbucket Cloud can reach the mirror using this name.

The setup wizard configuration cannot be changed after you click Submit configuration, so fill them in carefully. If you need to change the mirror's setup after it has been submitted, you'll need to stop the mirror, delete its home directory completely, and go back to step 2, Set up HTTPS on the mirror.

Advanced: automated setup...

As an alternative to using the setup wizard, you can automate the setup process without needing to navigate to the mirror in a browser. You can supply values for  <Mirror name> ,  <Mirror base URL> , and  <Primary server URL>  to your new mirror by adding the following properties to the  ${BITBUCKET_HOME}/shared/  file. These properties can only be applied on the first start of a new mirror, not after the mirror has already been set up.

1 2 3 setup.displayName=<Mirror name> setup.baseUrl=<Mirror base URL> plugin.mirroring.upstream.type=cloud

Once you have submitted your configuration, you'll be guided to connect your mirror to your Bitbucket workspace.

5. Connect the mirror to your Atlassian account

To connect your local mirror to an Atlassian account you'll need to have admin rights on your workspace. If you have admin rights you'll be prompted to grant the mirror access to your account.

An approved mirror will have access to all projects and repositories in your Bitbucket workspace. Bitbucket Smart Mirroring has been designed to require secure communication throughout and restrict all functionality to the appropriate privilege level (e.g., system administrator) to ensure the security of all your sensitive information. It is still your responsibility to set up mirrors with the same stringent security practices as Bitbucket Cloud. See How secure is Smart Mirroring? for more information.

Choose Bitbucket projects to mirror

Once the mirror has been connected, you'll get redirected to Bitbucket Cloud so you can decide which projects to mirror. Type in the name of a project in the search box and add it. Do this for each project you want to mirror.

You can always go back later to configure your mirrors in your workspace's Settings under Smart mirroring

You can also choose to mirror all projects, but note that this can't be undone without reinstalling the mirror.

Mirroring all projects cannot be undone later

If you decide later that you want to stop mirroring all projects, you'll have to remove and reinstall the mirror instance.

Work with the mirror

Once you have added projects to your mirror, see Work with Bitbucket Smart Mirroring to learn how to use the mirror in your day to day work.

Last modified on Dec 3, 2020
Cached at 3:47 PM on Apr 14, 2021 |

Additional Help

Ask the Community