Work with Bitbucket Smart Mirroring

Smart Mirroring for Bitbucket Cloud uses a local install of Bitbucket Data Center (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.

• If you're just getting started with Smart Mirroring, see Set up Bitbucket Smart Mirroring.

• If you want to mirror a Bitbucket Data Center instance, see Smart Mirroring instead.

How Smart Mirroring works

Smart Mirroring uses a local install of Bitbucket Data Center (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 team in Sydney can push to the mirror which will also push that change to the primary repository.

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

Once I've cloned from a mirror, am I supposed to push to the mirror as well?

No. To push to the repository you need to update the push URL to point to the upstream repository on Bitbucket Cloud. The command will look something like this:

$ git remote set-url --push origin git@bitbucket.org:<workspace_id>/repo.git

Check out the repository clone dialog to find the exact command which will set this up.

Synchronization

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

Authentication

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 workspace or all projects in that account. Every repository 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.

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.

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:

   1 $ git clone ssh://git@bitbucket-au.example.com:7999/upstream/PROJ/repo.git

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. You can now make any necessary changes to the clone you have created from the mirror and push those changes to the mirror. Your changes will also be reflected in the Bitbucket primary repository.

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, but any other members of your workspace will not be able to clone from that mirror any more.

Mirror a public repository

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 allowlisting

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

• You set the IP allowlist 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.