ContextQMD
Back to Gitlabhq

Migrate from Bitbucket Cloud

doc/user/import/bitbucket_cloud.md

19.0.08.8 KB
Original Source

{{< details >}}

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

{{< history >}}

  • Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5.
  • Parallel imports from Bitbucket Cloud introduced in GitLab 16.6 with a flag named bitbucket_parallel_importer. Disabled by default.
  • Enabled on GitLab.com in GitLab 16.6.
  • Generally available in GitLab 16.7. Feature flag bitbucket_parallel_importer removed.
  • An Imported badge on some imported items introduced in GitLab 17.2.

{{< /history >}}

Import your projects from Bitbucket Cloud to GitLab.

The Bitbucket Cloud importer imports a subset of items from Bitbucket Cloud.

Bitbucket Cloud itemImported
Repository description{{< yes >}}
Git repository data{{< yes >}}
Issues, including comments{{< yes >}}
Pull requests, including comments{{< yes >}}
Milestones{{< yes >}}
Wiki{{< yes >}}
Labels{{< yes >}}
Milestones{{< yes >}}
LFS objects{{< yes >}}
Pull request approvals{{< no >}}
Approval rules{{< no >}}

Importer workflow

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.

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 the Maintainer or Owner 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 (removed)

<!--- start_remove The following content will be removed on remove_date: '2026-08-15' -->

{{< details >}}

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

This feature was deprecated in GitLab 18.9 and removed in GitLab 19.0. Use Bitbucket Cloud API token instead.

<!--- end_remove -->

Generate a Bitbucket Cloud API token

To use the import API to import a Bitbucket Cloud repository, you must create a Bitbucket Cloud API token.

To generate a Bitbucket Cloud API token:

  1. Go to https://id.atlassian.com/manage-profile/security/api-tokens.

  2. Select Create API token with scopes.

  3. Enter a token name and expiration date, then select Next.

  4. Select Bitbucket and then Next.

  5. Select at least the following scopes:

    • read:repository:bitbucket
    • read:pullrequest:bitbucket
    • read:issue:bitbucket
    • read:wiki:bitbucket

  6. Select Create token and copy the token.

Import your Bitbucket Cloud repositories

  1. In the upper-right corner, select Create new ({{< icon name="plus" >}}) and New project/repository.
  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 Cloud repositories.
  2. Sign out of the Bitbucket account and import your Bitbucket Cloud 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.