How to re-install/re-register a single Bitbucket Smart Mirror

Still need help?

The Atlassian Community is here for you.

Ask the community

Platform Notice: Data Center Only - This article only applies to Atlassian products on the Data Center platform.

Note that this KB was created for the Data Center version of the product. Data Center KBs for non-Data-Center-specific features may also work for Server versions of the product, however they have not been tested. Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.

*Except Fisheye and Crucible

Summary

After experiencing an issue with a Bitbucket Smart Mirror, at times it may be appropriate to remove the existing data/configuration on the mirror and attempt re-registering it with the upstream server.

As mirrors are read-only, the process for resetting a mirror is non-destructive and can be accomplished fairly quickly - with the largest wait time only being the initial synchronization of the desired repositories back to the mirror after completing the steps below. 

Environment

  • Bitbucket Data Center 
  • Individual smart mirror(s) in use

Solution

All of the steps below (except for the first and last step) are applicable only to the mirror server.

None of these steps relating to the Bitbucket home should be performed on the upstream/primary Bitbucket instance.

  1. Delete the mirror connection on the front-end of the primary/upstream Bitbucket instance by navigating to Administration → Mirrors → <Mirror Name> → Delete
  2. Stop the service of the mirror on the mirror server
  3. On the filesystem of the mirror, navigate to the "$BITBUCKET_HOME/shared" directory and move/backup the config directory.
    • (info) The data directory is safe to delete, as the data there is just a copy of what's on the upstream. The config directory, though, can contain the Java Keystore being used by the mirror as well as the SSH key used for identifying the mirror to SSH clients - so we recommend backing that directory up.
  4. After backing up the config directory, delete the following data/config directories on the mirror:
    • $BITBUCKET_HOME/shared/data
    • $BITBUCKET_HOME/shared/config
      • (info) Using a command like the following can help retain the ssl-keystore file and SSH key mentioned in the previous step: 
      • find ./config -not -name 'ssl-keystore' -not -name 'ssh-server-keys.pem' -delete
  5. Start the mirror, and go through the setup screen to re-add it to the primary Bitbucket instance.
  6. On the upstream, navigate to the mirror and add the desired projects to be mirrored.

Once the projects have completed their initial synchronization, you should be good to go!

Otherwise, if you continue to experience issues with your mirror - it's recommended that your team review our mirror troubleshooting guide or reach out to our support team for further assistance.

Last modified on Jan 5, 2021

Was this helpful?

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