Bitbucket Exports And Imports Explained
Last Updated on September 26, 2024
As one of the leading platforms for distributed version control, Bitbucket is a hub that helps DevOps teams collaborate on code. This critical data, including source code, digital data, and we shouldn’t forget metadata that helps them to see the full picture of their work, is vital for their operations and business continuity. So, should they have the possibility to seamlessly import this data from Bitbucket and export to Bitbucket? The answer is yes.
Let’s dive into the details of export and import data in Bitbucket…
Top reasons to import and export data in Bitbucket
There are multiple reasons for an organization to opt for importing or exporting their data from Bitbucket. Starting from collaboration across teams to preserving project history, let’s look at the most important reasons to perform such operations:
Data migration to a new account or another VCS
Let’s imagine the situation in which you need to move your Bitbucket data, including repositories, projects, metadata, version history, issues, and permissions to another Bitbucket account or another version control system, e.g. GitHub or GitLab, or to a self-hosted version – Bitbucket Data Center. In this case, import and export capabilities can be at hand.
Backup and restore needs
To meet the Shared Responsibility Model and compliance requirements, you need to have backup. Import and export of Bitbucket data can partly cover this needs. As, it allows you to have a copy of your Bitbucket repository on your local disk, for example. So, when there is a need you can import your repository back to your Bitbucket.
Archiving purposes
For your organizational or compliance needs you may need to keep your data for long periods of time. Exporting repositories from Bitbucket to your local instance can meet this pain. Moreover, export of completed or inactive projects for long-term storage can help you free up space in the active Bitbucket environment.
Collaboration across teams
If you need to work and cooperate with teams that work with other version control systems, like GitHub or GitLab, you may need to import and export your data from time to time. In this case, if somebody works in GitHub and you need to push some code to the same project. you can import the GitHub repository to your Bitbucket project, and do your job.
Compliance and auditing
To meet strict compliance requirements, like SOC 2, ISO 27001 or NIS 2 (a new regulation that comes into force in October 2024), you need to guarantee that your data is secure, available and accessible. Exporting data from your Bitbucket, you get a copy of your repository that is necessary for audits and historical record-keeping.
Testing and development
By importing Bitbucket data, you can use it to test environments to simulate real-world scenarios, debug issues, or develop new features without impacting production data.
Also, you may need export and import capability for data analysis and reporting, Continuous Integration and Delivery, data consolidation, integration with other tools, preserving project history, and these reasons we can enlist more and more. Though, the most important here is how to export and import securely, fast, and without any data loss?
Bitbucket export and import tips & tricks – Bitbucket migration checklist
Before you start to export and import your data, it’s worth assessing all the risks. You’d better take some precautionary measures to be sure that nothing threatens your workflow, and during the exporting or importing process no data is lost.
So, let’s take a look at the so-called “requirements” before starting your export and import in Bitbucket:
- make sure that you can export or import repository with all its metadata,
- ensure that you have enough disk space for all the data you want to import and export,
- back up your data before importing or exporting your source code to have peace of mind that no data is lost… let’s not forget that source code is our critical asset!
- ask your developers to create a migration plugin module as add-ons can’t be migrated together with repositories,
- communicate your team about the migration process,
- use the same user directory for access controls
How to import data into Bitbucket – Step-by-step guide
Before we jump at describing how to import your data into Bitbucket, we need to mention some capabilities of the Bitbucket import feature. You can use Bitbucket importer only if you store your code in GitHub, CodePlex, Google Code, Subversion, SourceForge, or another Git-based hosting platform. If you have another alternative to host your source code or you don’t know the URL of the repository you want to export into Bitbucket, you will need to convert your code to Git. You can read more about it in the Atlassian Documentation.
Steps to import your data into Bitbucket
- First, you need to log in to your Bitbucket account, and go to repositories. There, you will need to click “Create” and in a dropdown menu select “Repository” as we want to import one repository into Bitbucket. In our case, we decided to import an existing repository from our GitHub account.
- Then, a new window will open – Create a new repository. As our task is not to create a new repository, but import the already existing one, you need to click “Import repository”.
- After that, you will see a new window “Import existing code”, where you will need to provide a valid URL to the repository you want to import into Bitbucket Cloud. As an example, we decided to import data from GitHub to Bitbucket, we use the URL to our old GitHub repository. Also, you will need to pick up the project (the existing one or you can create a new one if you need), where you want to import your repository, and provide a repository name.
4. Don’t forget about “Advanced settings” which you can access by expanding the button Advanced settings on your screen. Here you will be asked to provide description for the data you want to import (1), you can manage forking permissions (2), and you can choose a programming language for the repository you are importing (3). Though it’s not obligatory to add that information, it’s better to specify them.
5. Finally, when you click “Import repository”, you initiate the import of data. And when the process of importing is over, you will be notified if the migration process was successful or not. In our case, the importing of data from GitHub to GitLab was successful.
If you need to import a few repositories, you need to perform the above-mentioned steps a few times for each of your private repositories in your existing project on GitLab or GitHub. After that, you can check for the imported repositories in your existing project on Bitbucket.
How to export to Bitbucket – Step-by-step explanation
If you need to have a ZIP file of your Bitbucket repository on your local machine, you can manually download it. After you have your Bitbucket file on your local instance, you can keep it as a backup or upload it to another git hosting platform, for example, migrate that existing Bitbucket repo to GitHub or Gitlab.
Well, to export your Bitbucket data, you need to simply go to the git repository you want to export. Then, in the right corner expand “More” and select “Download repository”.
After that, you just need to figure out where you want to keep the downloaded file on your local machine.
That’s it! Now, the most important is to remember where you keep your exported repository from Bitbucket Cloud.
A few words about Bitbucket export and import using REST API architecture
In case you use Bitbucket Data Center, you can opt for the REST API architecture that Atlassian provides. Thus, you will be able to export your data to other platforms or to Bitbucket Cloud. Moreover, it can help you create your automated system.
How-to export data using API
Before you start an export job, you should remember that you can have only 2 concurrent exports per cluster node. Otherwise, the export will be rejected with an error. Moreover, you should confirm the URL of the repo or project you are about to export to be able to execute Bitbucket exports from your local instance. Usually this URL looks the following way:
https://bitbucket.com/projects/[name-of-the-project]/repos/[the-repository]
Here [name-of-the-project] means your project key, and [the-repository] represents your repository slug. Check Atlassian API documentation for the detailed explanation of the process and examples of the requests in different languages, including curl, Node.js, Java, Python, and PHP.
How-to import data using API
As for the Bitbucket Data Center importing, you should copy the import file you need to your target instance by copying into:
$BITBUCKET_HOME/shared/data/migration/import
Then, you should state the path relative to the import directory in the REST call. That’s important as if you file won’t be copied to this directory, your import job won’t work. For reference, we leave here a link to Atlassian’s documentation for importing Bitbucket data, as all the process is well documented there.
Are there any other ways to migrate data to Bitbucket?
Of course, if you search for other ways to migrate data into Bitbucket or from Bitbucket, you can find other options, for example Git Clone and Mirror commands. Though, they are useful for migrating data from one repo to another, e.g. from Bitbucket Cloud to Bitbucket Cloud, you still need to be very attentive not to miss some critical data during the cloning or mirroring process.
Git commands approach
- Git Clone command
For example, you can use the git clone command to create a clone of your repository:
git clone <repo_address> <directory> –no-tags –filter = blob: none
This approach will allow you to copy a project from a given address to the needed remote or local directory.
- Mirror command
In this case, you will need to do a git pull of your current master branch in local. For that, you can use:
git push – mirror destination-repository-url
This command will help you transfer all your branches, commit history, and tags to the new git repository.
GitProtect.io as a secure way to backup and migrate your Bitbucket Cloud data
Whether you need to do Bitbucket imports and exports for migration or backup needs, you can try a professional backup tool – GitProtect.io backup and Disaster Recovery software for Bitbucket. With GitProtect.io you will not only have a reliable copy of your Bitbucket data (in a few storage destinations!), but also meet the Shared Responsibility and compliance needs. Once you set up your GitProtect.io account and link your Bitbucket, GitHub, or/and GitLab environment to it you will be able to schedule an automated backup of your DevOps ecosystem, following the backup best practices for Bitbucket data protection.
Then, you can restore your data to the same or new Bitbucket account or use the cross-over recovery option with minimal effort – you can restore your data to another git hosting service, e.g GitLab or GitHub.
Before you go:
✍️ Subscribe to our DevOps X-Ray Newsletter to always stay up to date with the latest news in DevOps and DevSecOps.
🔎 Find out what security incidents Atlassian faced in 2023 and what were the causes of those threats.
📚 Learn how to build your Disaster Recovery strategy to meet any disaster scenario and build an uninterrupted workflow for your DevOps team.
📌 Try GitProtect.io backup and Disaster Recovery software for Bitbucket to have peace of mind that your data is safe during the migration process and any other event of failure.
📅 Schedule a live demo to talk about Bitbucket backup and best practices to protect your DevOps ecosystem.
