Migrate from Bitbucket Cloud

Import your projects from Bitbucket Cloud to GitLab.

When Bitbucket Cloud items are imported:

• References to pull requests and issues are preserved.
• Repository public access is retained. If a repository is private in Bitbucket Cloud, it’s created as private in GitLab.
• Imported issues, merge requests, and comments have an Imported badge in GitLab.

The importer workflow

When importing issues, pull requests, and comments, the Bitbucket Cloud importer:

• Uses the Bitbucket nickname of the author/assignee and tries to find the same Bitbucket identity in GitLab.
• If they don’t match or the user is not found in the GitLab database, sets the project creator (usually the current user that started the import process) as the author and keeps a reference on the issue about the original Bitbucket author.

For pull requests, the importer:

• Uses the source SHA, and if it does not exist in the repository, attempts to set the source commit to the merge commit SHA.
• Sets the merge request assignee to the author and sets reviewers with usernames matching Bitbucket identities in GitLab.
• Sets merge requests in GitLab to be either opened, closed, or merged.

For issues, the importer:

• Adds a label corresponding to the type of issue on Bitbucket. Either bug, enhancement, proposal or task.
• If the issue on Bitbucket was one of resolved, invalid, duplicate, wontfix, or closed, closes the issue on GitLab.

The Bitbucket Cloud importer creates any new namespaces (groups) if they don’t exist. If the namespace is taken, the repository is imported under the namespace of the user who started the import process.

Prerequisites

• You must enable the Bitbucket Cloud integration or ask your GitLab administrator to enable it. Enabled by default on GitLab.com.
• You must enable the Bitbucket Cloud import source or ask your GitLab administrator to enable it. Enabled by default on GitLab.com.
• You must have at least the Maintainer role on the destination group to import to.
• Pull requests in Bitbucket must have the same source and destination project and not be from a fork of a project. Otherwise, the pull requests are imported as empty merge requests.

For user contributions to be mapped, each user must complete the following before the project import:

1. Verify that the username in the Bitbucket account settings matches the public name in the Atlassian account settings. If they don’t match, modify the public name in the Atlassian account settings to match the username in the Bitbucket account settings.
2. Connect your Bitbucket account in GitLab profile service sign-in.

Generate a Bitbucket Cloud app password

If you want to use the import API to import a Bitbucket Cloud repository, you must create a Bitbucket Cloud app password.

To generate a Bitbucket Cloud app password:

1. Go to https://bitbucket.org/account/settings/.

2. In the Access Management section, select App passwords.

3. Select Create app password.

4. Enter password name.

5. Select at least the following permissions:

   Account: Email, Read
   Projects: Read
   Repositories: Read
   Pull Requests: Read
   Issues: Read
   Wiki: Read and Write

6. Select Create.

Import your Bitbucket repositories

1. On the left sidebar, at the top, select Create new ( ) and New project/repository. If you’ve turned on the new navigation, this button is in the upper-right corner.
2. Select Import project.
3. Select Bitbucket Cloud.
4. Sign in to Bitbucket, then select Grant access to give GitLab access to your Bitbucket account.
5. Select the projects you want to import, or import all projects. You can filter projects by name and select the namespace each project is imported for.
6. To import a project:
   • For the first time, select Import.
   • Subsequent times, select Re-import. Specify a new name and select Re-import again. Re-importing creates a new copy of the source project.

Troubleshooting

These sections contain possible solutions to issues you might encounter when importing from Bitbucket Cloud.

Import process used wrong account

Be sure to sign in to the correct account. If you’ve accidentally started the import process with the wrong account, follow these steps:

1. Revoke GitLab access to your Bitbucket account, essentially reversing the process when you imported your Bitbucket repositories.
2. Sign out of the Bitbucket account and import your Bitbucket repositories again.

User mapping fails despite matching names

For user mapping to work, the username in the Bitbucket account settings must match the public name in the Atlassian account settings.

If these names match but user mapping still fails, the user might have modified their Bitbucket username after connecting their Bitbucket account in the GitLab profile service sign-in.

To fix this issue, the user must verify that their Bitbucket external UID in the GitLab database matches their current Bitbucket public name, and reconnect if there’s a mismatch:

1. Use the API to get the authenticated user.
2. In the API response, the identities attribute contains the Bitbucket account that exists in the GitLab database. If the extern_uid doesn’t match the current Bitbucket public name, the user should reconnect their Bitbucket account in the GitLab profile service sign-in.
3. Following reconnection, the user should use the API again to verify that their extern_uid in the GitLab database now matches their current Bitbucket public name.

The user who imported the project must then delete the imported project and import again.

Related topics

• Migrate from Bitbucket Server
• Import API
• Import and export settings.
• Sidekiq configuration for imports.
• Running multiple Sidekiq processes.
• Processing specific job classes.