Troubleshooting, canceling and cleanup
When selecting individual repositories for exporting, the following rules apply:
- Once you select a fork in any hierarchy, the entire hierarchy will be included.
- If you only select the root repository, all forks will still be included.
Conflict resolution is automatic. If a project with the same name or key already exists, the imported project is renamed. After the import has finished, imported projects and repositories can be renamed or moved around as required.
For personal repositories, if a repository with the same name already exists, the imported repository is renamed.
If you cancel during export: The migration will stop immediately, and the archive is not usable.
If you cancel during import: The migration will complete importing the current repository, then stop. It's important to understand that if you cancel midway through the import, the fork hierarchy may not be complete and subsequent imports will not reuse already existing fork parents.
If you cancel while importing pull requests, the import will finish importing the current pull request, then stop.
If you cancel while importing Git data, no pull requests will be imported.
Import complete with errors
Every job (both import and export) has messages that you can query from the REST API.
If a job is completed but has warnings: you should read the warnings and decide if any action is required.
Errors mean something is broken or will fail.
The job will not complete, and you will need to identify and mitigate any errors you receive.
Repositories that remain "Initializing":
Whenever there is an error, there is a chance repositories will stay in a state that says "initializing". This are a technical error, and will not resolve on their own. Currently you will need to log a support case if you see this behaviour.
Rollback and Delete
There is no automatic rollback, you will need to manually go through and delete the data you do not want, before trying again.
Will source or target be down during migration?
Source and target will both remain available during a migration, during both import and export. This may negatively impact performance, and it should be run during low usage periods if possible.
Export archives may become bigger or less efficient if the instance is being used during migration. Because of this it is not recommended to use an instance during a migration.
What to do if your migration is corrupted
The export can be corrupted: When the job is completed and has no errors in the job messages, you can use the archive.
Import: there is a chance when the import fails, repos will stay in an initializing state. This is a fatal error, and cannot be remediated. You have to go and delete any initializing repos.
There is a REST endpoint which can be used to find all repos that are in state initializing.
Attachments in comments on pull requests
Attachments are uploaded and stored in the repository of the comment they added in. If a pull request comment references an attachment that was uploaded to a different repository, there is a possibility that the attachment will not be successfully imported. The following will be logged (and added as a warning to the import job) if an attachment is not successfully imported:
WARN c.a.s.i.m.DefaultImportContext Warning registered for job 1 of type com.atlassian.bitbucket.migration.import (RUNNING) against pr attachment: Could not find repository created with export ID '1,234'
Workaround: On the source instance, find the repository with the export ID that was logged when the attachment link failed to resolve on import (see example above).
If this repository was exported and imported onto the target instance, find the repository ID on the target instance, and update the repository ID in the attachment link in the comment text of any comments referencing it.
If this repository was not exported, replace the attachment link by downloading the attachment from the source instance and reattaching it to the comment on the target instance.