Importing
Before you start your import
Always carefully review the migration prerequisites before starting the import process.
Copy your import file to the target instance by copying into $BITBUCKET_HOME/shared/data/migration/import and specifying the path relative to the import directory in the REST call. Your import file must be copied to this directory or your import will not work.
After copying the file, it is recommended to verify its integrity and that it has been copied without errors. You can do this for example by calculating the export archive's MD5 sum (e.g. by using the `md5` tool or similar) on both the source and the target instance and checking that the result is the same.
Performing the import
Once you call the REST endpoint, the importer will begin to populate the database and file system.
You will not be prompted to resolve project-key collisions, they will be resolved automatically and a warning message will be added to the job. See section After the import below for how to query job messages.
You can perform the import using the below command:
curl -u <adminuser> -s -n -X POST -H 'Content-type: application/json' -d '{"archivePath":"Bitbucket_export_422.tar"}' http://localhost:7990/rest/api/1.0/migration/imports | jq .In the above example, the file 'Bitbucket_export_422.tar' was imported from the home/shared/data/migration/import directory. The archivePath parameter can either be relative or absolute.
Example
Relative (to $BITBUCKET_HOME/shared/data/migration/import):
{"archivePath":"Bitbucket_export_422.tar"}The following request values are required for import (REST Documentation):
| Value | Description |
|---|---|
| URL | /rest/api/1.0/migration/imports |
| HTTP verb | POST |
| HTTP header | Content-type: application/json |
| Authentication | Basic |
The response will contain the job ID, which is important to query the status of the job later.
During the import
You can query the following specific REST point to see progress:
watch -n1 'curl -u <adminuser> -s -n -X GET http://localhost:7990/rest/api/1.0/migration/imports/<Job ID> | jq .'Replace <Job ID> with the "id" value that was returned from request that started the import job.
The following request values are required to query the progress (REST Documentation):
Description | Value |
|---|---|
| URL | /rest/api/1.0/migration/imports/<Job ID> |
| HTTP verb | GET |
| Authentication | Basic |
During the import process, no modifications are made to the source instance, so you can roll back to it if anything goes wrong.
After the import
On successful completion, the job state will change to "completed". If any errors occurred, the job state will change to ABORTED for fatal errors or FAILED.
To check for warnings or errors:
curl -u <adminuser> -s -n -X GET http://localhost:7990/rest/api/1.0/migration/imports/<Job ID>/messages | jq .Replace <Job ID> with the "id" value that was returned from the request that started the import job.
The following values are required to check for warnings or errors (REST Documentation):
Description | Value |
|---|---|
| URL | /rest/api/1.0/migration/exports/<Job ID>/messages |
| HTTP verb | GET |
| Authentication | Basic |
Warning messages should be dealt with on a case-by-case basis, it generally means that some data was not completely imported, or that name collisions were resolved.
Error messages mean that the import was not successful and some data was only partially imported or not at all. Please see the troubleshooting section for more information.
Canceling the import
Import jobs are not canceled instantaneously like export jobs. During import, once the cancel request has been accepted, the following checkpoints will apply, then the job will stop:
- after the current fork hierarchy has been imported and verified.
- before the next repository is imported.
- before the next pull request is imported.
This means that some repositories might be missing from a fork hierarchy, or some pull requests might be missing from repositories. Git data in a repository will always be consistent if the job was canceled cleanly.
To cancel the import:
curl -u <adminuser> -s -n -X POST -H 'Content-type: application/json' http://localhost:7990/rest/api/1.0/migration/imports/<job ID>/cancelReplace <Job ID> with the "id" value that was returned from the request that started the import job.
The following request values are required to cancel the import (REST Documentation):
Description | Value |
|---|---|
| URL | /rest/api/1.0/migration/imports/<job ID>/cancel |
| HTTP verb | POST |
| Authentication | Basic |