Smart Mirroring

Administering Bitbucket Server

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

This feature is only available for customers with an active Bitbucket Data Center license. Get an evaluation license to try it out, or purchase a license now.

Smart Mirroring can greatly improve Git clone speeds for distributed teams working with large repositories. Large repositories that take hours to clone from a Bitbucket instance over the Internet from the other side of the world can take minutes when cloned from a local mirror on a fast network.

As your team grows and becomes more distributed, so will the need to clear up congestion resulting from an increasing number of continuous integration (CI) builds. Mirror farms can handle this issue by taking mirrors and clustering them into farms to reduce the time spent waiting for those build results.

If you're ready to start mirroring your repositories, you can jump straight to the Set up a mirror or Set up and configure a mirror farm page and follow the steps there, or read on to learn more about the benefits of using a mirror. If you have mirrors already configured, you might be searching for instructions on how to Clone a mirror repository.


Check out the latest on-demand webinar, How to support your geo-distributed teams with Atlassian Data Center.

In this webinar, learn how Atlassian Data Center provides performance at scale for your distributed teams and get access to:

  • Best practices on instance setup and configuration for distributed team work
  • A deep dive on some of the latest geo-performance features like CDN and Mirror Farms
  • Tips for scaling teamwork globally

About Smart Mirroring

Many software development teams using Git have large repositories. This is a result of either storing lots of historical information, using monolithic repositories, or storing large binary files (sometimes all three). Companies with distributed software development teams often have little control over the network performance available to them between sites. In combination, this leads to a loss of development time when developers have to wait long periods to clone a large repository from across the world.

Smart mirroring prevents this lost development time by allowing you to set up live mirrors that host copies of repositories in remote locations. These mirrors automatically keep any repository hosted on them in sync with the primary Bitbucket Data Center instance. Users in those remote locations may clone and fetch repositories from the mirror and get identical content, only faster. You can choose to mirror a selection of projects, or mirror all repositories in all projects from the primary instance. 

How it works

Mirrors run the same Bitbucket application as a full Bitbucket Server instance, but they are configured to mirror an primary Bitbucket Data Center instance, where the primary copy of all your repositories is hosted. 

When a user clones or fetches from a mirror, the mirror automatically delegates the authentication and authorization of their credentials back to the primary server. No extra user management is required on standalone mirrors or mirror nodes in a farm. All the users, groups, and permissions of the primary Bitbucket instance (whether provided by the built-in user directory and permission system or by your own user directories and/or custom extensions) are always replicated exactly on all mirrors. 


Self-healing is one of the main design principles for smart mirroring. Mirrors have the ability to detect and recover from a number of error scenarios, while All operations retry with exponential backoff. Smart mirroring also includes an anti-entropy system (the farm vet) which verifies the consistency of a mirror against the primary every 3 minutes. For more information and help with monitoring the health of your mirror farm, see Monitoring your mirror farm

Ready to get started setting up a mirror?

Be sure to read Set up a mirror or Set up and configure a mirror farm for detailed instructions on installing a mirror or mirror farm.

Don't have Bitbucket Data Center yet? Purchase a Bitbucket Data Center license, or get an evaluation license to try Bitbucket Data Center.

Last modified on Feb 2, 2021

Was this helpful?

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