From 2fb28dddfc7848a90294c2008b5d672a305a8596 Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axilleas@axilleas.me>
Date: Tue, 30 Aug 2016 15:42:40 +0200
Subject: [PATCH] Refactor Bitbucket integration documentation
---
doc/integration/bitbucket.md | 190 +++++++++++++++++++++--------------
doc/integration/omniauth.md | 4 +-
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
--
GitLab