info:To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
info:To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
---
---
# Import your project from Bitbucket Server to GitLab **(FREE)**
# Import your project from Bitbucket Server **(FREE)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20164) in GitLab 11.2.
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20164) in GitLab 11.2.
NOTE:
NOTE:
The Bitbucket Server importer does not work with [Bitbucket Cloud](https://bitbucket.org).
This process is different than [importing from Bitbucket Cloud](bitbucket.md).
Use the [Bitbucket Cloud importer](bitbucket.md) for that.
Import your projects from Bitbucket Server to GitLab with minimal effort.
From Bitbucket Server, you can import:
The Bitbucket importer can import:
- Repository description
- Git repository data
- Repository description (GitLab 11.2+)
- Pull requests
- Git repository data (GitLab 11.2+)
- Pull request comments
- Pull requests (GitLab 11.2+)
- Pull request comments (GitLab 11.2+)
When importing, repository public access is retained. If a repository is private in Bitbucket, it's
When importing, repository public access is retained. If a repository is private in Bitbucket, it's
created as private in GitLab as well.
created as private in GitLab as well.
## Limitations
## Import your Bitbucket repositories
- GitLab doesn't allow comments on arbitrary lines of code, so any Bitbucket comments out of bounds
are inserted as comments in the merge request.
- Bitbucket Server allows multiple levels of threading. GitLab import collapses this into one thread
and quote part of the original comment.
- Declined pull requests have unreachable commits, which prevents the GitLab importer from
generating a proper diff. These pull requests show up as empty changes.
- Pull request approvals are not imported.
- Attachments in Markdown are not imported.
- Task lists are not imported.
- Emoji reactions are not imported.
- Project filtering does not support fuzzy search (only `starts with` or `full match strings` are
supported).
## How it works
The Bitbucket Server importer works as follows:
1. The user is prompted to enter the URL, username, and password (or personal access token) to log in to Bitbucket.
These credentials are preserved only as long as the importer is running.
1. The importer attempts to list all the current repositories on the Bitbucket Server.
1. Upon selection, the importer clones the repository and import pull requests and comments.
### User assignment
When issues/pull requests are being imported, the Bitbucket importer tries to
Prerequisites:
find the author's email address with a confirmed email address in the GitLab
user database. If no such user is available, the project creator is set as
the author. The importer appends a note in the comment to mark the original
creator.
The importer creates any new namespaces (groups) if they don't exist or in
- An administrator must have enabled the **Bitbucket Server** in
the case the namespace is taken, the repository is imported under the user's
**Admin > Settings > General > Visibility and access controls > Import sources**.
namespace that started the import process.
- Review the importer's [limitations](#limitations).
#### User assignment by username
To import your Bitbucket repositories:
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218609) in GitLab 13.4.
1. Sign in to GitLab.
> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default.
1. On the top bar, select **New** (**{plus}**).
> - It's disabled on GitLab.com.
1. Select **New project/repository**.
> - It's not recommended for production use.
1. Select **Import project**.
> - To use it in GitLab self-managed instances, ask a GitLab administrator to enable it.
1. Select **Bitbucket Server**.
1. Log in to Bitbucket and grant GitLab access to your Bitbucket account.
1. Select the projects to import, or import all projects. You can filter projects by name and select
the namespace for which to import each project.
WARNING:
## Limitations
This feature might not be available to you. Check the **version history** note above for details.
If you've enabled this feature, the importer tries to find a user in the GitLab user database with
- GitLab doesn't allow comments on arbitrary lines of code. Any out-of-bounds Bitbucket comments are
the author's:
inserted as comments in the merge request.
- Bitbucket Server allows multiple threading levels. The importer collapses this into one thread and
quotes part of the original comment.
- Declined pull requests have unreachable commits. This prevents the importer from generating a
proper diff. These pull requests show up as empty changes.
- Project filtering doesn't support fuzzy search. Only starts with or full match strings are
supported.
-`username`
The following aren't imported:
-`slug`
-`displayName`
If the user is not found by any of these properties, the project creator is set as the author.
- Pull request approvals
- Attachments in Markdown
- Task lists
- Emoji reactions
##### Enable or disable User assignment by username
## User assignment
User assignment by username is under development and not ready for production use. It is
When issues and pull requests are importing, the importer tries to find the author's email address
deployed behind a feature flag that is **disabled by default**.
with a confirmed email address in the GitLab user database. If no such user is available, the
[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md)
project creator is set as the author. The importer appends a note in the comment to mark the
can enable it.
original creator.
To enable it:
The importer creates any new namespaces (groups) if they don't exist. If the namespace is taken, the
repository imports under the namespace of the user who started the import process.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218609) in GitLab 13.4 [with a flag](../../../administration/feature_flags.md) named `bitbucket_server_user_mapping_by_username`. Disabled by default.
