diff options
Diffstat (limited to 'doc/user/project/import/bitbucket_server.md')
| -rw-r--r-- | doc/user/project/import/bitbucket_server.md | 158 |
1 files changed, 69 insertions, 89 deletions
diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index da47b673c29..4e3642eb3bd 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -5,130 +5,110 @@ group: Import 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. NOTE: -The Bitbucket Server importer does not work with [Bitbucket Cloud](https://bitbucket.org). -Use the [Bitbucket Cloud importer](bitbucket.md) for that. +This process is different than [importing from Bitbucket Cloud](bitbucket.md). -Import your projects from Bitbucket Server to GitLab with minimal effort. +From Bitbucket Server, you can import: -The Bitbucket importer can import: - -- Repository description (GitLab 11.2+) -- Git repository data (GitLab 11.2+) -- Pull requests (GitLab 11.2+) -- Pull request comments (GitLab 11.2+) +- Repository description +- Git repository data +- Pull requests +- Pull request comments When importing, repository public access is retained. If a repository is private in Bitbucket, it's 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). +Prerequisites: -## How it works +- An administrator must have enabled the **Bitbucket Server** in + **Admin > Settings > General > Visibility and access controls > Import sources**. +- Review the importer's [limitations](#limitations). -The Bitbucket Server importer works as follows: +To import your Bitbucket repositories: -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. +1. Sign in to GitLab. +1. On the top bar, select **New** (**{plus}**). +1. Select **New project/repository**. +1. Select **Import project**. +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. -### User assignment +## Limitations -When issues/pull requests are being imported, the Bitbucket importer tries to -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. +- GitLab doesn't allow comments on arbitrary lines of code. Any out-of-bounds Bitbucket comments are + 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. -The importer creates any new namespaces (groups) if they don't exist or in -the case the namespace is taken, the repository is imported under the user's -namespace that started the import process. +The following aren't imported: -#### User assignment by username +- Pull request approvals +- Attachments in Markdown +- Task lists +- Emoji reactions -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218609) in GitLab 13.4. -> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. -> - It's disabled on GitLab.com. -> - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to enable it. +## User assignment -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +When issues and pull requests are importing, the importer tries to 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. -If you've enabled this feature, the importer tries to find a user in the GitLab user database with -the author's: +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. -- `username` -- `slug` -- `displayName` +### User assignment by username -If the user is not found by any of these properties, the project creator is set as the author. +> - [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. +> - Not recommended for production use. -##### Enable or disable User assignment by username +FLAG: +On self-managed GitLab and GitLab.com, by default this feature is not available. To make it +available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) +named `bitbucket_server_user_mapping_by_username`. This feature is not ready for production use. -User assignment by username is under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can enable it. +With this feature enabled, the importer tries to find a user in the GitLab user database with the +author's: -To enable it: +- `username` +- `slug` +- `displayName` -```ruby -Feature.enable(:bitbucket_server_user_mapping_by_username) -``` +If no user matches these properties, the project creator is set as the author. -To disable it: +## Troubleshooting -```ruby -Feature.disable(:bitbucket_server_user_mapping_by_username) -``` +### General -## Import your Bitbucket repositories +If the GUI-based import tool does not work, you can try to: -Prerequisite: +- Use the [GitLab Import API](../../../api/import.md#import-repository-from-bitbucket-server) + Bitbucket Server endpoint. +- Set up [repository mirroring](../repository/mirror/index.md). + It provides verbose error output. -- An administrator must have enabled the importer in - **Admin > Application Settings > Visibility and access controls > Import sources**. +See the [troubleshooting section](bitbucket.md#troubleshooting) +for Bitbucket Cloud. -To import your Bitbucket repositories: +### LFS objects not imported -1. Sign in to GitLab. -1. On the top bar, select **New** (**{plus}**). -1. Select **New project/repository**. -1. Select **Import project**. -1. Select **Bitbucket Server**. -1. Log in to Bitbucket and grant GitLab access to your Bitbucket account. -1. Select the projects that you'd like to import or import all projects. - You can filter projects by name and select the namespace - each project will be imported for. +If the project import completes but LFS objects can't be downloaded or cloned, you may be using a +password or personal access token containing special characters. For more information, see +[this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/337769). -## Automate group and project import **(PREMIUM)** +## Related topics For information on automating user, group, and project import API calls, see [Automate group and project import](index.md#automate-group-and-project-import). - -## Troubleshooting - -If the GUI-based import tool does not work, you can try to: - -- Use the [GitLab Import API](../../../api/import.md#import-repository-from-bitbucket-server) Bitbucket server endpoint. -- Set up [Repository Mirroring](../repository/mirror/index.md), which provides verbose error output. - -See the [troubleshooting](bitbucket.md#troubleshooting) section for [Bitbucket](bitbucket.md). |