Work with Bitbucket Smart Mirroring

Still need help?

The Atlassian Community is here for you.

Ask the community

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 work with a Smart Mirror once it's set up and running.

On this page:

How Smart Mirroring works

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

For example, a local team in Austin might interact with Bitbucket Cloud (the primary), whereas a remote team, say in Sydney, clones and pulls from the mirror, which is hosted close to them. The remote team pushes to the primary – the mirror is read-only, and doesn't accept pushes.

All other interactions, such as repository browsing and using pull requests, are provided by Bitbucket Cloud – Bitbucket Server doesn't have a web UI when functioning as a mirror.



The mirror and the primary Bitbucket Cloud are automatically kept in sync. 


When a user interacts with the mirror, the mirror automatically delegates authentication to the primary. No extra user management is required on mirrors, and all the users, groups and permissions of the primary Bitbucket Cloud are replicated exactly on the mirror.


Decide which projects you want to mirror

It is only possible to mirror individual projects in your team account or all projects in that account. Every repo of the selected projects will get mirrored. If you decide to mirror all projects you won't be able to go back to mirroring just individual projects – you'll have to remove and reinstall the mirror instance to switch from mirroring all to mirroring individual projects.

Pull from the mirror, push to Bitbucket

Bitbucket Smart Mirrors are read-only and you can't push to them. When you're using Smart Mirroring, you'll perform Git clone, pull (or fetch) operations against the mirror, but push to Bitbucket Cloud. This means you'll need to set up different remote URLs for the mirror and Bitbucket Cloud. You'll probably do this after having cloned from the mirror.

To update your push URL

  1. In the repository on Bitbucket Cloud, click the Clone button.
  2. Select a mirror in the Clone from dropdown, then copy the command that looks like this:

    git remote set-url --push origin ssh://

  3. In your terminal, navigate to the cloned directory then run the command.

Your remote push URL now points to Bitbucket Cloud (the primary).

You'll need to do this for each mirrored repository you work with.


Use your mirror with Git LFS

Bitbucket Smart Mirroring seamlessly support Git LFS. If your repo contains any GIT LFS files the mirror will automatically sync them in the background. You can use all your common Git or Git LFS commands to fetch any repo that contains Git LFS files.


Use your mirror with Sourcetree

It's easy to use Smart Mirroring with Sourcetree, the Atlassian desktop client for Git and Mercurial. If you're just getting started with Sourcetree, you may find the Learn Sourcetree with Bitbucket tutorial helpful.

When using Sourcetree, you just need to remember that you clone and pull from the mirror, and push to Bitbucket. 

Clone from the mirror

To clone a repository from the mirror:

  1. Navigate to the repository in Bitbucket.
  2. Click the Clone button.
  3. Use the Clone from dropdown to select the mirror closest to you – different mirrors have different clone URLs.
  4. Copy the clone URL (for either SSH or HTTPS).
    If you are using the SSH protocol, ensure your public key is correctly configured. 
  5. In a terminal window, change to the local directory where you want to clone your repository.
  6. Type git clone then paste the copied clone URL. 
    The command and clone URL together will look something like this:

    $ git clone ssh://

If the clone succeeds, a new sub-directory is created on your local drive. This directory has the same name as the Bitbucket repository that you cloned. The clone contains the files and metadata that Git requires to maintain the changes you make to the source files.

Note that mirrors are read-only. After cloning from a mirror, you need to update your remote push URL to point to Bitbucket, as described in the following section.

Update the push URL for Bitbucket

After you've cloned from the mirror you'll need to set the push URL to point to Bitbucket.

To update your push URL in SourceTree
  1. In the repository on Bitbucket Server, click Clone.
  2. Select a mirror in the Clone from dropdown, then copy the command that looks like this:

    git remote set-url --push origin ssh://

    You won't need the commands, only the push URL (the bit that starts after ssh://).

  3. Within SourceTree, open your repository settings.
  4. Select the origin repository path, then click Edit Config File...
    A text editor appears. 
  5. Within the Config File, under [remote "origin"], enter pushurl = then paste only the push URL after =.
    The config file should look like this:

    pushurl = ssh://
  6. Save and close the Config File. Click OK to close the Repository Settings screen.

Your remote push URL within SourceTree now points to the primary Bitbucket Data Center instance.


Connect a mirror to a different Bitbucket account

You can change the Bitbucket account that the mirror is connected to:

  1. Go to your account admin settings and select Smart mirroring.
  2. Select the mirror you want to reconnect to a different account.
  3. Remember the mirror base URL.
  4. Delete the mirror from the current account.
  5. Visit the mirror base URL and click add it again.
  6. Select the new account you want to connect your mirror to and grant access.

Remove a mirror

If you remove your mirror from your account your team will not be able to clone from that mirror any more.

Mirror a public repo

If you mirror a project that has a public repo, then the address of the mirror is publicly exposed. Bitbucket will advertise that mirror to every visitor to the Bitbucket site, and those visitors will not be required to log in to access that repo. This can have a performance impact on the mirror because it will receive a greater number of requests.

Note that the mirror has to be publicly accessible so that Bitbucket can connect with the mirror.

There are a couple of ways to mitigate the impact of this increase in traffic:

Move public repos to a project in Bitbucket that is not mirrored

This is the recommended approach, and avoids mirroring the public repos at all. Those repos can still be public on Bitbucket, of course.

Note that this approach still exposes the IP address of your mirror, but the mirror will appear as disabled.

IP whitelisting

An IP whitelist allows you to restrict access to the mirror to just some incoming IP addresses.

  • You set the IP whitelist on your external-facing firewall.
  • The mirror needs outbound access to the Bitbucket inbound address and inbound access from the Bitbucket outbound addresses. See Bitbucket Cloud IP addresses for the list of IP addresses that Bitbucket uses. 

Note that this approach still exposes the IP address of your mirror, but the mirror will appear as disabled.

Last modified on Sep 13, 2017

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.