Refactor Bitbucket integration documentation

2 files changed, 119 insertions, 75 deletions

diff --git a/doc/integration/bitbucket.md b/doc/integration/bitbucket.md
index 94c845c29a4..16e54102113 100644
--- a/doc/integration/bitbucket.md
+++ b/doc/integration/bitbucket.md
@@ -1,127 +1,155 @@
-# Integrate your server with Bitbucket
+# Integrate your GitLab server with Bitbucket
 
-Import projects from Bitbucket and login to your GitLab instance with your Bitbucket account.
+Import projects from Bitbucket and login to your GitLab instance with your
+Bitbucket account.
 
-To enable the Bitbucket OmniAuth provider you must register your application with Bitbucket.
-Bitbucket will generate an application ID and secret key for you to use.
+## Overview
 
-1.  Sign in to Bitbucket.
+You can set up Bitbucket as an OAuth provider so that you can use your
+credentials to authenticate into GitLab or import your projects from Bitbucket.
 
-1.  Navigate to your individual user settings (Manage account) or a team's settings (Manage team), depending on how you want the application registered. It does not matter if the application is registered as an individual or a team - that is entirely up to you.
+- To use Bitbucket as an OmniAuth provider, follow the [Bitbucket OmniAuth
+  provider](#bitbucket-omniauth-provider) section.
+- To import projects from Bitbucket, follow both the
+  [Bitbucket OmniAuth provider](#bitbucket-omniauth-provider) and
+  [Bitbucket project import](#bitbucket-project-import) sections.
 
-1.  Select "OAuth" in the left menu.
+## Bitbucket OmniAuth provider
+
+> **Note:**
+Make sure to first follow the [Initial OmniAuth configuration][init-oauth]
+before proceeding with setting up the Bitbucket integration.
+
+To enable the Bitbucket OmniAuth provider you must register your application
+with Bitbucket. Bitbucket will generate an application ID and secret key for
+you to use.
 
+1.  Sign in to Bitbucket.
+1.  Navigate to your individual user settings (Manage account) or a team's
+    settings (Manage team), depending on how you want the application registered.
+    It does not matter if the application is registered as an individual or a
+    team - that is entirely up to you.
+1.  Select "OAuth" in the left menu.
 1.  Select "Add consumer".
+1.  Provide the required details:
 
-1.  Provide the required details.
-    - Name: This can be anything. Consider something like `<Organization>'s GitLab` or `<Your Name>'s GitLab` or something else descriptive.
-    - Application description: Fill this in if you wish.
-    - Callback URL: leave blank.
-    - URL: The URL to your GitLab installation. 'https://gitlab.company.com'
+    | Item | Description |
+    | :--- | :---------- |
+    | **Name** | This can be anything. Consider something like `<Organization>'s GitLab` or `<Your Name>'s GitLab` or something else descriptive. |
+    | **Application description** | Fill this in if you wish. |
+    | **Callback URL** | Leave blank. |
+    | **URL** | The URL to your GitLab installation, e.g., `https://gitlab.example.com`. |
 
-1.  Grant at least the following permissions.
-    - Account: Email
-    - Repositories: Read
-    
-1.  Select "Save".
+1.  Grant at least the following permissions:
 
-1.  Select your newly created OAuth consumer.
+    ```
+    Account: Email
+    Repositories: Read
+    ```
 
+1.  Select "Save".
+1.  Select your newly created OAuth consumer.
 1.  You should now see a Key and Secret in the list of OAuth customers.
     Keep this page open as you continue configuration.
-
 1.  On your GitLab server, open the configuration file.
 
     For omnibus package:
 
     ```sh
-      sudo editor /etc/gitlab/gitlab.rb
+    sudo editor /etc/gitlab/gitlab.rb
     ```
 
     For installations from source:
 
     ```sh
-      cd /home/git/gitlab
+    cd /home/git/gitlab
 
-      sudo -u git -H editor config/gitlab.yml
+    sudo -u git -H editor config/gitlab.yml
     ```
 
 1.  See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings.
-
 1.  Add the provider configuration:
 
     For omnibus package:
 
     ```ruby
-      gitlab_rails['omniauth_providers'] = [
-        {
-          "name" => "bitbucket",
-          "app_id" => "YOUR_KEY",
-          "app_secret" => "YOUR_APP_SECRET",
-          "url" => "https://bitbucket.org/"
-        }
-      ]
+    gitlab_rails['omniauth_providers'] = [
+      {
+        "name" => "bitbucket",
+        "app_id" => "YOUR_KEY",
+        "app_secret" => "YOUR_APP_SECRET",
+        "url" => "https://bitbucket.org/"
+      }
+    ]
     ```
 
     For installation from source:
 
-    ```
-      - { name: 'bitbucket', app_id: 'YOUR_KEY',
+    ```yaml
+    - { name: 'bitbucket',
+        app_id: 'YOUR_KEY',
         app_secret: 'YOUR_APP_SECRET' }
     ```
 
 1.  Change 'YOUR_KEY' to the key from the Bitbucket application page from step 7.
-
 1.  Change 'YOUR_APP_SECRET' to the secret from the Bitbucket application page from step 7.
-
 1.  Save the configuration file.
-
-1.  If you're using the omnibus package, reconfigure GitLab (```gitlab-ctl reconfigure```).
-
 1.  Restart GitLab for the changes to take effect.
 
-On the sign in page there should now be a Bitbucket icon below the regular sign in form.
-Click the icon to begin the authentication process. Bitbucket will ask the user to sign in and authorize the GitLab application.
-If everything goes well the user will be returned to GitLab and will be signed in.
+On the sign in page there should now be a Bitbucket icon below the regular sign
+in form. Click the icon to begin the authentication process. Bitbucket will ask
+the user to sign in and authorize the GitLab application. If everything goes
+well the user will be returned to GitLab and will be signed in.
 
 ## Bitbucket project import
 
-To allow projects to be imported directly into GitLab, Bitbucket requires two extra setup steps compared to GitHub and GitLab.com.
+To allow projects to be imported directly into GitLab, Bitbucket requires two
+extra setup steps compared to [GitHub](github.md) and [GitLab.com](gitlab.md).
 
-Bitbucket doesn't allow OAuth applications to clone repositories over HTTPS, and instead requires GitLab to use SSH and identify itself using your GitLab server's SSH key.
+Bitbucket doesn't allow OAuth applications to clone repositories over HTTPS, and
+instead requires GitLab to use SSH and identify itself using your GitLab
+server's SSH key.
 
-### Step 1: Public key
+To be able to access repositories on Bitbucket, GitLab will automatically
+register your public key with Bitbucket as a deploy key for the repositories to
+be imported. Your public key needs to be at `~/.ssh/bitbucket_rsa` which
+translates to `/var/opt/gitlab/.ssh/bitbucket_rsa` for Omnibus packages and to
+`/home/git/.ssh/bitbucket_rsa.pub` for installations from source.
 
-To be able to access repositories on Bitbucket, GitLab will automatically register your public key with Bitbucket as a deploy key for the repositories to be imported. Your public key needs to be at `~/.ssh/bitbucket_rsa.pub`, which will expand to `/var/opt/gitlab/.ssh/bitbucket_rsa` for omnibus package and to `/home/git/.ssh/bitbucket_rsa.pub` for installations from source.
+---
 
-If you have that file in place, you're all set and should see the "Import projects from Bitbucket" option enabled. If you don't, do the following:
+Below are the steps that will allow GitLab to be able to import your projects
+from Bitbucket.
 
-1. Create a new SSH key:
+1. Make sure you [have enabled the Bitbucket OAuth support](#bitbucket-omniauth-provider).
+1. Create a new SSH key with an **empty passphrase**:
 
     ```sh
     sudo -u git -H ssh-keygen
     ```
 
-    When asked `Enter file in which to save the key` specify the correct path, eg. `/var/opt/gitlab/.ssh/bitbucket_rsa` or `/home/git/.ssh/bitbucket_rsa`.
-    Make sure to use an **empty passphrase**.
+    When asked to 'Enter file in which to save the key' enter:
+    `/var/opt/gitlab/.ssh/bitbucket_rsa` for Omnibus packages or
+    `/home/git/.ssh/bitbucket_rsa` for installations from source. The name is
+    important so make sure to get it right.
 
-1. Configure SSH client to use your new key:
+    > **Warning:**
+    This key must NOT be associated with ANY existing Bitbucket accounts. If it
+    is, the import will fail with an `Access denied! Please verify you can add
+    deploy keys to this repository.` error.
+
+1. Next, you need to to configure the SSH client to use your new key. Open the
+   SSH configuration file of the `git` user:
 
-    Open the SSH configuration file of the git user.
-    
-    For omnibus package:
-    
-    ```sh
-      sudo editor /var/opt/gitlab/.ssh/config
     ```
-    
-    For installations from source:    
+    # For Omnibus packages
+    sudo editor /var/opt/gitlab/.ssh/config
 
-    ```sh
-      sudo editor /home/git/.ssh/config
+    # For installations from source
+    sudo editor /home/git/.ssh/config
     ```
 
-    Add a host configuration for `bitbucket.org`.
+1. Add a host configuration for `bitbucket.org`:
 
     ```sh
     Host bitbucket.org
@@ -129,28 +157,44 @@ If you have that file in place, you're all set and should see the "Import projec
       User git
     ```
 
-### Step 2: Known hosts
-
-To allow GitLab to connect to Bitbucket over SSH, you need to add 'bitbucket.org' to your GitLab server's known SSH hosts. Take the following steps to do so:
-
-1. Manually connect to 'bitbucket.org' over SSH, while logged in as the `git` account that GitLab will use:
+1. Save the file and exit.
+1. Manually connect to `bitbucket.org` over SSH, while logged in as the `git`
+   user that GitLab will use:
 
     ```sh
     sudo -u git -H ssh bitbucket.org
     ```
 
-1.  Verify the RSA key fingerprint you'll see in the response matches the one in the [Bitbucket documentation](https://confluence.atlassian.com/display/BITBUCKET/Use+the+SSH+protocol+with+Bitbucket#UsetheSSHprotocolwithBitbucket-KnownhostorBitbucket'spublickeyfingerprints) (the specific IP address doesn't matter):
+    That step is performed because GitLab needs to connect to Bitbucket over SSH,
+    in order to add `bitbucket.org` to your GitLab server's known SSH hosts.
+
+1.  Verify the RSA key fingerprint you'll see in the response matches the one
+    in the [Bitbucket documentation][bitbucket-docs] (the specific IP address
+    doesn't matter):
 
     ```sh
-    The authenticity of host 'bitbucket.org (207.223.240.182)' can't be established.
-    RSA key fingerprint is 97:8c:1b:f2:6f:14:6b:5c:3b:ec:aa:46:46:74:7c:40.
+    The authenticity of host 'bitbucket.org (104.192.143.1)' can't be established.
+    RSA key fingerprint is SHA256:zzXQOXSRBEiUtuE8AikJYKwbHaxvSc0ojez9YXaGp1A.
     Are you sure you want to continue connecting (yes/no)?
     ```
 
-1. If the fingerprint matches, type `yes` to continue connecting and have 'bitbucket.org' be added to your known hosts.
+1. If the fingerprint matches, type `yes` to continue connecting and have
+   `bitbucket.org` be added to your known SSH hosts. After confirming you should
+   see a permission denied message. If you see an authentication successful
+   message you have done something wrong. The key you are using has already been
+   added to a Bitbucket account and will cause the import script to fail. Ensure
+   the key you are using CANNOT authenticate with Bitbucket.
+1. Restart GitLab to allow it to find the new public key.
 
-1. Your GitLab server is now able to connect to Bitbucket over SSH.
+Your GitLab server is now able to connect to Bitbucket over SSH. You should be
+able to see the "Import projects from Bitbucket" option on the New Project page
+enabled.
 
-1. Restart GitLab to allow it to find the new public key.
+## Acknowledgemts
+
+Special thanks to the writer behind the following article:
+
+- http://stratus3d.com/blog/2015/09/06/migrating-from-bitbucket-to-local-gitlab-server/
 
-You should now see the "Import projects from Bitbucket" option on the New Project page enabled.
\ No newline at end of file
+[init-oauth]: omniauth.md#initial-omniauth-configuration
+[bitbucket-docs]: https://confluence.atlassian.com/bitbucket/use-the-ssh-protocol-with-bitbucket-cloud-221449711.html#UsetheSSHprotocolwithBitbucketCloud-KnownhostorBitbucket%27spublickeyfingerprints
diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md
index 46b260e7033..8a55fce96fe 100644
--- a/doc/integration/omniauth.md
+++ b/doc/integration/omniauth.md
@@ -102,8 +102,8 @@ To change these settings:
         block_auto_created_users: true
     ```
 
-Now we can choose one or more of the Supported Providers listed above to continue
-the configuration process.
+Now we can choose one or more of the [Supported Providers](#supported-providers)
+listed above to continue the configuration process.
 
 ## Enable OmniAuth for an Existing User