Add Bitbucket Server importer docs

Add details for https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/20164.

6 files changed, 84 insertions, 8 deletions

diff --git a/doc/integration/bitbucket.md b/doc/integration/bitbucket.md
index 2afcb052536..bf587b5b296 100644
--- a/doc/integration/bitbucket.md
+++ b/doc/integration/bitbucket.md
@@ -1,4 +1,4 @@
-# Integrate your GitLab server with Bitbucket
+# Integrate your GitLab server with Bitbucket Cloud
 
 NOTE: **Note:**
 You need to [enable OmniAuth](omniauth.md) in order to use this.
diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md
index e3d625cc621..f2f47a6b208 100644
--- a/doc/user/project/import/bitbucket.md
+++ b/doc/user/project/import/bitbucket.md
@@ -1,17 +1,18 @@
-# Import your project from Bitbucket to GitLab
+# Import your project from Bitbucket Cloud to GitLab
 
-Import your projects from Bitbucket to GitLab with minimal effort.
+Import your projects from Bitbucket Cloud to GitLab with minimal effort.
 
 ## Overview
 
 >**Note:**
-The [Bitbucket integration][bb-import] must be first enabled in order to be
+The [Bitbucket Cloud integration][bb-import] must be first enabled in order to be
 able to import your projects from Bitbucket. Ask your GitLab administrator
 to enable this if not already.
 
->**Note:**  
-The BitBucket importer currently only works with BitBucket's cloud offering 
-(bitbucket.org) and does not work with BitBucket Server (aka Stash).
+>**Note:**
+The Bitbucket Cloud importer works only with Bitbucket.org, not with Bitbucket
+Server (aka Stash). If you are trying to import projects from Bitbucket Server, use
+[the Bitbucket Server importer](bitbucket_server.md).
 
 - At its current state, the Bitbucket importer can import:
   - the repository description (GitLab 7.7+)
@@ -48,7 +49,7 @@ namespace that started the import process.
 
     ![New project in GitLab](img/bitbucket_import_new_project.png)
 
-1. Click on the "Bitbucket" button
+1. Click on the "Bitbucket Cloud" button.
 
     ![Bitbucket](img/import_projects_from_new_project_page.png)
 
diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md
new file mode 100644
index 00000000000..1318c439f9a
--- /dev/null
+++ b/doc/user/project/import/bitbucket_server.md
@@ -0,0 +1,75 @@
+# Import your project from Bitbucket Server to GitLab
+
+Import your projects from Bitbucket Server to GitLab with minimal effort.
+
+## Overview
+
+>**Note:**
+The BitBucket Server importer does not work with Bitbucket Cloud (aka bitbucket.org). Use the [Bitbucket Cloud importer](bitbucket.md) for that.
+
+- 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.
+1. Bitbucket Server allows multiple levels of threading. GitLab
+import will collapse this into one discussion and quote part of the original
+comment.
+1. Declined pull requests have unrecahable commits, which prevents the GitLab
+importer from generating a proper diff. These pull requests will show up as
+empty changes.
+1. Attachments in Markdown are currently not imported.
+1. Task lists are not imported.
+1. Emoji reactions are not imported
+
+## 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 login to Bitbucket.
+   These credentials are preserved only as long as the importer is running.
+1. The importer will attempt to list all the current repositories on the Bitbucket Server.
+1. 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.
+
+## Importing your Bitbucket repositories
+
+1. Sign in to GitLab and go to your dashboard.
+1. Click on **New project**.
+
+    ![New project in GitLab](img/bitbucket_import_new_project.png)
+
+1. Click on the "Bitbucket Server" button. If the button is not present, enable the importer in
+    `Admin` -> `Application Settings` -> `Visbility and access controls` -> `Import sources`.
+
+    ![Bitbucket](img/import_projects_from_new_project_page.png)
+
+1. Enter your Bitbucket Server credentials.
+
+    ![Grant access](img/bitbucket_server_import_credentials.png)
+
+1. Click on the projects that you'd like to import or **Import all projects**.
+   You can also select the namespace under which each project will be
+   imported.
+
+    ![Import projects](img/bitbucket_server_import_select_project.png)
diff --git a/doc/user/project/import/img/bitbucket_server_import_credentials.png b/doc/user/project/import/img/bitbucket_server_import_credentials.png
new file mode 100644
index 00000000000..70b26e89d49
--- /dev/null
+++ b/doc/user/project/import/img/bitbucket_server_import_credentials.png
diff --git a/doc/user/project/import/img/bitbucket_server_import_select_project.png b/doc/user/project/import/img/bitbucket_server_import_select_project.png
new file mode 100644
index 00000000000..e5b1b89e6a3
--- /dev/null
+++ b/doc/user/project/import/img/bitbucket_server_import_select_project.png
diff --git a/doc/user/project/import/img/import_projects_from_new_project_page.png b/doc/user/project/import/img/import_projects_from_new_project_page.png
index 97ca30b2087..40402eae226 100644
--- a/doc/user/project/import/img/import_projects_from_new_project_page.png
+++ b/doc/user/project/import/img/import_projects_from_new_project_page.png