Summary

This document outlines the steps to restore Git history for a deleted repository in Bitbucket. It provides three distinct methods depending on the availability of backups and repository clones. It is important to note that this procedure will only restore the Git history and not restore repository details, permissions, settings, hooks, or pull requests.

Environment

Bitbucket Server and Datacenter, version 4.12.0 and newer

Cause

The root cause typically involves the accidental deletion of a repository from the Bitbucket. The problem can be replicated by deleting a repository without ensuring a backup or clone is available.

Solution

Case #1 - Using a Backup, recommended option

This option can be used if a repository backup is available. The backup can be taken using one of the Data backup strategy.

It is the recommended option because it is based on the repository backup available on the server. Compared to a cloned repository, this will contain all the branches and tags, not just those available on a local clone.

• Locate the bare repository from the backup.
• Identify the repository via repository-config or verify it in $BITBUCKET_HOME/shared/data/repositories.

#>***********************************************
# THIS FILE IS MAINTAINED BY ATLASSIAN BITBUCKET
# IT CONTAINS NO USER-SERVICEABLE PARTS.
#>***********************************************
[bitbucket]
	hierarchy = <hierarchy id>
	project = <project key>
	repository = <repository slug>

• Create a new repository in Bitbucket Server and obtain its clone URL.

• Navigate to the backup directory and execute the following:

# update the repository URL with the value of the newly created repository
git remote add origin <new repository clone URL>

# push the Git history (including branches and tags)
git push --all origin
git push --tags origin

Case #2 - Using a Clone from a Test Server

• Clone the repository from the test server to a local directory, ensuring all branches and tags are checked out.
• Create a new repository in Bitbucket Server and enable 'Allow LFS' if necessary.
• In the cloned repository, perform:

# Install Git LFS client if it was not already installed
git lfs install

# Retrieve all LFS objects
git lfs fetch --all

# Add the new origin to your clone. $target_repo_url is an empty repository created in the Bitbucket application
git remote add $target_instance_name $target_repo_url

# Push all LFS objects
git lfs push --all 

# Push the Git history (including branches and tags)
git push --all origin
git push --tags origin

Case #3 - Using a Local Clone

• Use a local clone of the repository to recreate it in Bitbucket Server as described in Case #2. Note that this may not contain the complete history.

Other Notes

• Ensure all configurations are checked before proceeding with any restoration method.

• Regular backups are recommended to prevent data loss.

• Validate compatibility of the backup method with the version of Bitbucket Server in use.

Existing feature request

The feature request allowing a restore of a repository including all its details is available here: 

BSERV-4586 - As an admin, I want to be able to export and restore projects or repositories individually, so that the metainformation (e.g. pull requests details) are preserved