DOCS add gitlab MR decoration

1 files changed, 46 insertions, 16 deletions

diff --git a/server/sonar-docs/src/pages/analysis/pr-decoration.md b/server/sonar-docs/src/pages/analysis/pr-decoration.md
index af13c78a4be..335ee200f7e 100644
--- a/server/sonar-docs/src/pages/analysis/pr-decoration.md
+++ b/server/sonar-docs/src/pages/analysis/pr-decoration.md
@@ -18,7 +18,7 @@ Click your ALM provider below to expand the instructions on decorating your Pull
 |
 | ### Creating a GitHub App
 |
-| To enable PR decoration in GitHub checks, an instance administrator needs to create a GitHub App:
+| To add Pull Request decoration in GitHub checks, an instance administrator needs to create a GitHub App:
 |
 | 1. Follow Steps 1–4 [here](https://developer.github.com/apps/building-github-apps/creating-a-github-app/) to start creating your GitHub App.
 | 1. Under **GitHub App name**, give your app a name (such as SonarQubePRChecks).
@@ -32,9 +32,9 @@ Click your ALM provider below to expand the instructions on decorating your Pull
 |	| Pull Requests       | Read-only    |
 |	| Commit statuses     | Read-only    |
 |
-| 1. Under "Where can this GitHub App be installed?," select **Any account**.
-| 1. Click **Create GitHub App**. This will take you to your new GitHub App's page.
-| 1. Scroll down to the bottom of your app page and click **Generate Private Key**. This downloads a `.pem` file that you'll use in the **Setting your global settings** section.  
+| 1. Under "Where can this GitHub App be installed?," select **Any account**.  
+| 2. Click **Create GitHub App**. This will take you to your new GitHub App's page.  
+| 3. Scroll down to the bottom of your app page and click **Generate Private Key**. This downloads a `.pem` file that you'll use in the **Setting your global settings** section.  
 |
 | ### Installing your app 
 |
@@ -44,9 +44,9 @@ Click your ALM provider below to expand the instructions on decorating your Pull
 |
 | To set your global settings in SonarQube:
 |
-| 1. Navigate to **Administration > Configuration > General Settings > Pull Request Decoration**.
-| 1. Select the **GitHub** tab.
-| 1. Click the **Create configuration** button.
+| 1. Navigate to **Administration > Configuration > General Settings > Pull Request Decoration**.  
+| 2. Select the **GitHub** tab.  
+| 3. Click the **Create configuration** button.  
 |
 | From here, set your **Configuration Name**, **GitHub Instance URL**, **GitHub App ID**, and your GitHub App's **Private Key** (that was generated above in the **Creating a GitHub App** section).
 |
@@ -61,16 +61,17 @@ Click your ALM provider below to expand the instructions on decorating your Pull
 |
 | *Minimum BitBucket Server version 5.15*
 |
-| To add PR decoration on Bitbucket Server, you need to update your global and project settings. 
+| To add Pull Request decoration on Bitbucket Server, you need to update your global and project settings. 
 |
 | ### Setting your global settings
 |
-| A Bitbucket Server user account is used to decorate Pull Requests. You need a [Personal Access Token](https://confluence.atlassian.com/bitbucketserver0515/personal-access-tokens-961275199.html) from this account with **Write** permission.
+| A Bitbucket Server user account is used to decorate Pull Requests. We recommend creating a dedicated Bitbucket Server account with Administrator permissions to decorate Pull Requests. You need a [Personal Access Token](https://confluence.atlassian.com/bitbucketserver0515/personal-access-tokens-961275199.html) from this account with **Write** permission for the repositories that will be analyzed.
 | 
-| To set your global settings in SonarQube:  
+| To set your global settings in SonarQube:
+|
 | 1. Navigate to **Administration > Configuration > General Settings > Pull Request Decoration**.
-| 1. Select the **Bitbucket Server** tab.
-| 1. Click the **Create configuration** button. 
+| 2. Select the **Bitbucket Server** tab.
+| 3. Click the **Create configuration** button.
 |
 | From here, set your  **Configuration name**, **Bitbucket Server URL**, and the **Personal Access Token** of the account you're using to decorate your Pull Requests.
 |
@@ -83,13 +84,14 @@ Click your ALM provider below to expand the instructions on decorating your Pull
 [[collapse]]
 | ## Azure DevOps Server
 |
-|To add PR decoration on Azure DevOps Server, you need to update your global and project settings. 
+| To add Pull Request decoration on Azure DevOps Server, you need to update your global and project settings. 
 |
 | ### Setting your global settings
 |
-| An Azure DevOps Server user account is used to decorate Pull Requests. You need a [Personal Access Token](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=tfs-2017&tabs=preview-page) from this account with the scope authorized for **Code > Read & Write**.
+| An Azure DevOps Server user account is used to decorate Pull Requests. We recommend creating a dedicated Azure DevOps Server account with Administrator permissions to decorate Pull Requests. You need a [Personal Access Token](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=tfs-2017&tabs=preview-page) from this account with the scope authorized for **Code > Read & Write** for the repositories that will be analyzed.
+|
+| To set your global settings in SonarQube:  
 |
-| To set your global settings in SonarQube:
 | 1. Navigate to **Administration > Configuration > General Settings > Pull Request Decoration**.
 | 1. Select the **Azure DevOps Server** tab.
 | 1. Click the **Create configuration** button.
@@ -102,8 +104,36 @@ Click your ALM provider below to expand the instructions on decorating your Pull
 |
 | Go to **Administration > General Settings > Pull Request Decoration** and select your **Configuration name**.
 
+[[collapse]]
+| ## GitLab
+|
+| To add Merge Request decoration to GitLab, you need to update your global and project settings.
+|
+| ### Setting your global settings
+|
+| A GitLab user account is used to decorate Merge Requests. We recommend creating a dedicated GitLab account with at least **Reporter** [permissions](https://docs.gitlab.com/ee/user/permissions.html) to decorate Merge Requests. This user account needs permissions to leave comments. You need a Personal Access Token from this account with the scope authorized for **api** for the repositories that will be analyzed.
+|
+| To set your global settings in SonarQube:  
+|
+| 1. Navigate to **Administration > Configuration > General Settings > Pull Request Decoration**.
+| 1. Select the **GitLab** tab.
+| 1. Click the **Create configuration** button.
+|
+| From here, set your **Configuration name** and the **Personal Access Token** of the account you're using to decorate your Merge Requests.
+|
+| **Note:** Make sure the Configuration name is succinct and easily recognizable as it will be used at the project level to identify the correct ALM configuration.
+|
+| ### Setting your project settings
+|
+| Go to **Administration > General Settings > Pull Request Decoration** and select your **Configuration name**.
+
 ## Multiple ALM instances
-SonarQube lets you decorate Pull Requests from multiple ALM instances. To do this, you can create a configuration (as shown in the previous section) for each of your ALM instances. That instance configuration can then be assigned to the appropriate projects. 
+
+It's possible to decorate Pull Requests from multiple ALM instances. To do this, you can create a configuration (as shown in the previous section) for each of your ALM instances. That instance configuration can then be assigned to the appropriate projects.
+
+As part of [Developer Edition](https://redirect.sonarsource.com/editions/developer.html), you can create one configuration for each ALM. 
+
+As part of [Enterprise Edition](https://redirect.sonarsource.com/editions/enterprise.html) and [above](https://www.sonarsource.com/plans-and-pricing/), you can create multiple configurations for each ALM.
 
 ## Issue links
 During pull request decoration, individual issues will be linked to their SonarQube counterparts automatically. However, for this to work correctly, the instance's **Server base URL** (**[Administration > Configuration > General Settings > General > General](/#sonarqube-admin#/admin/settings/)**) must be set correctly. Otherwise the links will default to `localhost`.