How to Migrate From Bitbucket to GitHub
“The only constant in life is change”. This seemingly banal phrase has been known to mankind for about 2500 years. It is attributed to Heraclitus of Ephesus, the Greek philosopher who claimed that everything was constantly changing and that this is the nature of the universe. Nothing disappears and nothing appears, everything just changes. Well, I won’t go into philosophy any further, but this introduction is not accidental. In our case, the change means switching the hosting service on which we keep our git repository and source code – transferring our Bitbucket repository with its metadata to GitHub.
Most common causes of Bitbucket to GitHub repo transfer
We’ll focus on how to migrate from Bitbucket to GitHub later. Let’s start by answering the question “why?”. There can be many reasons, either subjective or objective. Sometimes it’s a question of price or license limitations. The number of available private or public repositories may also be of key importance to us and migration to another platform may be more profitable. Or it can be a necessary measure – on February 15th Atlassian stopped its support for server versions. Thus, Bitbucket Server users need to think carefully about whether they want to migrate to either Bitbucket Cloud or Bitbucket DC or migrate to another Git hosting service, like GitHub.
The reason may also be other software that we want to use in our company. For example, Bitbucket integrates directly with Jira, Bamboo, Crucible, and Jenkins. There can be many reasons, even the GUI and web interface will suit us more on a different platform, or we just want to change something in the course of learning and our own development, although this reason applies more to individual users, not enterprises. Anyway, we made a decision that we want to perform Bitbucket repository to GitHub repository migration. What’s next?
Bitbucket and GitHub: the differences
Let’s go over the differences between the two services in detail. What are their pros and cons? I mentioned above the platforms with which Bitbucket easily integrates. What does it look like on the GitHub side? Here, direct integration occurs with services such as Azure, Google Cloud, Amazon, or Heroku. In addition, GitHub offers GitHub Pages and GitHub Gist services, which can also influence our decisions.
In the case of open-source projects, GitHub offers unlimited public Git repositories for free, while Bitbucket rather targets corporate and private repository clients. There is also a desktop client on the GitHub side, which can be a big advantage for many people. In addition, we have SVN support here. On the other hand, the Atlassian Marketplace is a huge advantage of the competition. Of course, GitHub also has this type of service for Extensions and Third-party app integrations, however, Bitbucket is more powerful in this area. Mainly because of other Atlassian products that can easily cooperate with it.
Let’s check the popularity of both platforms. Due to its openness to open-source projects, GitHub has the advantage here, currently, over 100 million users are registered there. On the other hand, we have “only” over 10 million accounts. However, Bitbucket focuses on business customers, so this difference in numbers should come as no surprise.
Learn more about the differences between Bitbucket and GitHub is our dedicated blog post – Git Battles: GitHub vs. Bitbucket – What to choose for your development team?
Bitbucket to GitHub migration
Now that we have learned more or less the reasons for migration and the differences between various hosting services, let’s finally get down to business and check how to perform such a migration.
First of all, let’s make sure that our repository is up-to-date, that is, that every developer has integrated his code, all tags, and other necessary data are available in the external repository. If so, the migration process is relatively easy. As an example, I prepared a simple test repository with two branches and two tags.
We should now start by cloning the source repository to the local machine.
When making a clone, remember to download all branches and tags. We can do it manually, but I recommend using the –mirror parameter here, which will do it for us. An important note here, as cloning with this parameter, will trigger the –bare parameter. Effect? The repository cloned in this way means that we will not see Working Tree, but only the contents of the .git directory.
git clone –mirror <Bitbucket_repo_address>
Whether we use –mirror or not, it’s important that we now have all the necessary information locally. The next step is to set a new address, the so-called origin which will point to the target repository. For the sake of order, it is worth removing the previous one first, i.e. the one pointing to the source repository that we just cloned.
git remote rm origin
git remote add origin <GitHub_repo_address>
Before taking the next step, it is worth checking that we have all the branches and tags locally.
After correctly downloading all the necessary data we can sync the local copy with the new target repository address in GitHub.
git push origin –all
git push –tags
or just simply
git push –mirror
After completing all the steps, check the result in GitHub.
To summarize – for successful Bitbucket to GitHub migration you only need few steps:
- make sure all necessary data is in the repository
- clone the repo prepared in this way
- make sure we have checked out all tags and branches
- replace the remote origin address
- push the changes to the target repo
How secure are your repos and metadata? Don’t push luck – secure your code with the first professional GitHub, Bitbucket, and GitLab backup.
Bitbucket repository to to GitHub migration with GitHub Importer
Another available option to migrate from Bitbucket to GitHub is to use GitHub Importer. This option is more suitable for the Bitbucket Cloud version, about the Server one we will talk a bit later. So, if you decided to use this GitHub native tool, you should understand that in this case you import your Bitbucket repository to a new GitHub repository. So, here are the steps you should follow:
- First log in to your GitHub and in the upper-right corner click “+”, and then click Import repository:
- Enter the URL of the Bitbucket repository you want to import in “Your old repository’s clone URL“.
- Then you need to determine who is the owner of the repository, thus, under “Owner” choose the dropdown menu and pick your personal account or an organization.
- Then, in “Name” provide a name for the new GitHub repository.
- Choose the visibility of your new GitHub repository in “Privacy”.
- Check the information you’ve provided, and if everything is right click the Begin Import.
- In this stage, your old repository may require your credentials, so you will need to provide your login information. In the case of SAML SSO or 2-factor authentication, you will need to provide your personal access tokens with the repository read permissions instead of the password in the “Password” field.
- Then, just click Submit.
- If you have many projects in your old project’s git clone URL, you will need to choose those projects you want to import, and after that click Submit.
- After the operation, you will get an email notification, that your data from the Bitbucket repository has been imported into the GitHub repository.
Bitbucket Server to GitHub Enterprise Cloud migration
As we have already mentioned Atlassian stopped support for its server versions on February 15th. It means that Bitbucket server users will no longer get updates and their environment can become more vulnerable to the threats. Among the options Atlassian offers – migrate to Bitbucket Cloud or update to Bitbucket Data Center, – Bitbucket Server users can migrate their data to GitHub Enterprise Cloud using GitHub CLI. To do that, you should follow the next steps:
- Install the GitHub CLI’s BBS2GH extension, if it is your first migration. In the case you already have the BBS2GH extension installed, you need to update it to the newest version, because GitHub usually updates the BBS2GH extension of the GitHub CLI every week. To make sure that you use the newest version, just update the extension using gh extension upgrade github/gh-bbs2gh.
- After that you should create a personal access token to access the organization and set it as an environment variable before using the BBS2GH extension for migrating your data to GitHub. What’s more, don’t forget to set environment variables for your Bitbucket Server password and username, as well. If you run your Bitbucket Server instance on Windows, you will need to set environment variables for your SMB password.
- Then you will need to set up blob storage, so that GitHub CLI could use your data for migration.
- Migrate the repository using gh bbs2gh migrate-repo command. As an alternative, you can use GitHub CLI to create an archive of your data, then manually download that archive, and use GitHub CLI to continue the process of migration.
Bitbucket to GitHub repository migration risks
There is such a popular joke that people are divided into those who do backups and those who will start one day. We are clever and we should belong to the first group. Migration always carries the risk of data loss. Rather, we will not lose the code or the history of changes, because Git itself will not allow it, but losing, for example, tags is very possible if we do something carelessly. Plus, according to Murphy’s law, something can always go wrong, and then backup is all the more necessary. So before any operation, let’s make sure we have a well-made and available backup in case a quick restore is needed. You will not regret it.
Cross-over data recovery – the simplest method ever
Having a reliable third-party backup is not only for keeping copies of your data safe and sound on some independent storage. Backup should be inextricably linked with recovery options. After all, instant data restore and Disaster Recovery (DR), both enable our company to keep on running when any event of failure occurs. But sometimes the recovery & DR features can be adapted for easy and secure data migration. That is why GitProtect.io enables cross-over recovery between GitHub, Bitbucket, and GitLab. It means that you can make a copy of your Bitbucket repositories and metadata, then choose this copy to restore, and then choose a new or existing GitHub organization as a data recovery destination. And basically, that’s it. This is all you need to do to migrate your entire (or chosen) Bitbucket data to GitHub. It’s even easier than it sounds.
Before you go:
✍️ Subscribe to GitProtect DevSecOps X-Ray Newsletter and always stay up-to-date with the latest DevOps and security insights
📚 Find out the top reasons why back up DevOps tools during the migration process
🔎 Download the GitHub backup guide to always have it at hand and know what to do in emergencies
📅 Schedule a live custom demo and learn more about GitProtect backups for your DevOps data protection
📌 Or try GitProtect backups for your GitLab, Bitbucket, GitHub, or Jira ecosystem to guarantee data protection and ensure continuous workflow
