Import your project from Bitbucket Server to GitLab

Introduced in GitLab 11.2.

NOTE: Note: The Bitbucket Server importer does not work with Bitbucket Cloud. Use the Bitbucket Cloud importer for that.

Import your projects from Bitbucket Server to GitLab with minimal effort.

Overview

• In its current state, the Bitbucket importer can import:
  • the repository description (GitLab 11.2+)
  • the Git repository data (GitLab 11.2+)
  • the pull requests (GitLab 11.2+)
  • the pull request comments (GitLab 11.2+)
• Repository public access is retained. If a repository is private in Bitbucket it will be created as private in GitLab as well.

Limitations

1. Currently GitLab doesn't allow comments on arbitrary lines of code, so any Bitbucket comments out of bounds will be inserted as comments in the merge request.

2. Bitbucket Server allows multiple levels of threading. GitLab import will collapse this into one thread and quote part of the original comment.

3. Declined pull requests have unreachable commits, which prevents the GitLab importer from generating a proper diff. These pull requests will show up as empty changes.

4. Attachments in Markdown are currently not imported.

5. Task lists are not imported.

6. Emoji reactions are not imported.

7. LFS objects are not imported.

   NOTE: Note: To import a repository including LFS objects from a Bitbucket server repository, use the Repo by URL importer.

8. Project filtering does not support fuzzy search (only starts with or full match strings are currently supported)

How it works

The Bitbucket Server importer works as follows:

1. The user will be 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.
2. The importer will attempt to list all the current repositories on the Bitbucket Server.
3. Upon selection, the importer will clone the repository and import pull requests and comments.

User assignment

When issues/pull requests are being imported, the Bitbucket importer tries to find the author's e-mail address with a confirmed e-mail address in the GitLab user database. If no such user is available, the project creator is set as the author. The importer will append a note in the comment to mark the original creator.

The importer will create any new namespaces (groups) if they don't exist or in the case the namespace is taken, the repository will be imported under the user's namespace that started the import process.

User assignment by username

Alternatively, user assignment by username is available behind a bitbucket_server_user_mapping_by_username feature flag. The importer will try to find a user in the GitLab user database using author's username or slug or displayName. Falls back to author's email if user is not found by username. Similarly to user assignment by email, if no such user is available, the project creator is set as the author.

To enable or disable user assignment by username:

Start a Rails console.

# Enable
Feature.enable(:bitbucket_server_user_mapping_by_username)

# Disable
Feature.disable(:bitbucket_server_user_mapping_by_username)

Importing your Bitbucket repositories

1. Sign in to GitLab and go to your dashboard.

2. Click on New project.

3. Click on the "Bitbucket Server" button. If the button is not present, enable the importer in Admin > Application Settings > Visibility and access controls > Import sources.

   

4. Enter your Bitbucket Server credentials.

   

5. Click on the projects that you'd like to import or Import all projects. You can also filter projects by name and select the namespace under which each project will be imported.

   

Troubleshooting

If the GUI-based import tool does not work, you can try to:

• Use the GitLab Import API Bitbucket server endpoint.
• Set up Repository Mirroring, which provides verbose error output.

See the troubleshooting section for Bitbucket.