DOCS update PR pages and add multiple ALM section

2 files changed, 108 insertions, 74 deletions

diff --git a/server/sonar-docs/src/pages/analysis/pr-decoration.md b/server/sonar-docs/src/pages/analysis/pr-decoration.md
new file mode 100644
index 00000000000..9cbe6cc6868
--- /dev/null
+++ b/server/sonar-docs/src/pages/analysis/pr-decoration.md
@@ -0,0 +1,94 @@
+---
+title: Decorating Pull Requests
+url: /analysis/pr-decoration/
+---
+
+_Pull Request decoration is available as part of [Developer Edition](https://redirect.sonarsource.com/editions/developer.html) and [above](https://www.sonarsource.com/plans-and-pricing/)._
+
+You can add SonarQube analysis and a Quality Gate to your Pull Requests (PR) directly in your ALM provider's interface.
+
+## Pull Request Decoration by provider
+
+Click your ALM provider below to expand the instructions on decorating your Pull Requests.
+
+[[collapse]]
+| ## GitHub Enterprise  
+|
+|*Minimum GitHub Enterprise Version 2.14*
+|
+| ### Creating a GitHub App
+|
+| To enable PR 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).
+| 1. GitHub requires a **Homepage URL** and a **Webhook URL**. These values aren't important for Pull Request decoration, so you can use any URL (such as `https://www.sonarqube.org/`).
+| 1. Grant access for the following **Permissions**
+|
+|	| Permission          | Access       |
+|	|---------------------|--------------|
+|	| Checks              | Read & write |
+|	| Repository metadata | Read-only    |
+|	| 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.  
+|
+| ### Installing your app
+| To install your app in your GitHub organizations:
+|
+| 1. Go to your GitHub App URL. GitHub App URLs are formatted as: `https://<your-github-enterprise-address>/github-apps/<YourAppName>`.  
+|	For example, if your GitHub Enterprise address is `github-enterprise-1.yoursite.com` and your app name is `SonarQubePRChecks`, your GitHub App URL will be `https://github-enterprise-1.yoursite.com/github-apps/SonarQubePRChecks`.
+| 2. From your GitHub App page, click the **Install** or **Configure** button.
+| 3. Choose the organization where you want to install your app from the list.
+| 4. Click the **Install** button. 
+|
+| ### Setting your global settings
+|
+| Go to **[Administration > General Settings > Pull Requests](/#sonarqube-admin#/admin/settings?category=pull_request/)**, select the **GitHub Enterprise** tab, and click the **Create configuration** button to set your Configuration Name, ALM Instance URL, GitHub App ID, and your GitHub App's Private Key (that was generated above in the **Creating a GitHub App** section).
+|
+| **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**, select your Configuration Name (created in the previous section), then set your Repository identifier.
+
+[[collapse]]
+| ## Bitbucket Server
+|
+| *Minimum BitBucket Server version 5.15*
+|
+| To add PR decoration on Bitbucket Server, you need to update your global and project settings. 
+|
+| ### Setting your global settings
+|
+| Go to **[Administration > General Settings > Pull Requests](/#sonarqube-admin#/admin/settings?category=pull_request/)**, select the **Bitbucket Server** tab, and click the **Create configuration** button to set your  Configuration name, Bitbucket Server URL, and Personal Access token.
+|
+| **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**, select your Configuration name, then set your Project Key and Repo Slug.
+
+[[collapse]]
+| ## Azure DevOps Server
+|
+|To add PR decoration on Azure DevOps Server, you need to update your global and project settings. 
+|
+| ### Setting your global settings
+|
+| Go to **[Administration > General Settings > Pull Requests](/#sonarqube-admin#/admin/settings?category=pull_request/)**, select the **Azure DevOps Server** tab, and click the **Create configuration** button to set your  Configuration name and Personal Access token.
+|
+| **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. 
+
+## 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`.
\ No newline at end of file
diff --git a/server/sonar-docs/src/pages/analysis/pull-request.md b/server/sonar-docs/src/pages/analysis/pull-request.md
index 98c55e23135..498162d58d2 100644
--- a/server/sonar-docs/src/pages/analysis/pull-request.md
+++ b/server/sonar-docs/src/pages/analysis/pull-request.md
@@ -1,93 +1,33 @@
 ---
-title: Pull Request Analysis
+title: Overview
 url: /analysis/pull-request/
 ---
 
-
-
 _Pull Request analysis is available as part of [Developer Edition](https://redirect.sonarsource.com/editions/developer.html) and [above](https://www.sonarsource.com/plans-and-pricing/)._
 
+You can see your Pull Requests in {instance} from the branches and pull requests dropdown menu of your project.
 
-Pull Requests (PRs) are visible in {instance} from the branches and pull requests dropdown menu of your project.
+Pull Request analysis allows you to see your Pull Request's Quality Gate and analysis in the {instance} interface:
 
-PR analysis allows you to:
+![Pull Request Analysis.](/images/pranalysis.png)
 
-* see your PR's Quality Gate status in the {instance} UI.
-* automatically decorate your PRs with {instance} issues in your SCM provider's interface.
+## Pull Request Decoration
+You can also add Pull Request decoration that shows the Pull Request analysis and Quality Gate directly in your ALM's interface. See [Decorating Pull Requests](/analysis/pr-decoration/) for more information on setting it up.
 
-## Quality Gate
+## Pull Request Quality Gate
 
-The PR quality gate:
+A [Quality Gate](/user-guide/quality-gates/) lets you ensure you are meeting your organization's quality policy and that you can merge your Pull Request. The Pull Request Quality Gate:
 * **Focuses on new code** – The PR quality gate only uses your project's quality gate conditions that apply to "on New Code" metrics.
-* **Assigns a status** – Each PR shows a quality gate status reflecting whether it Passed (green) or Failed (red).
+* **Assigns a status** – Each PR shows a quality gate status reflecting whether it Passed or Failed.
 
-When PR decoration is enabled, {instance} publishes the status of the analysis (Quality Gate) on the PR.
-
-PR analyses on {instance} are deleted automatically after 30 days with no analysis. This can be updated in **Configuration > General > Number of days before purging inactive short living branches**. 
+PR analyses on {instance} are deleted automatically after 30 days with no analysis. This can be updated in **Administration > Configuration > General > Number of days before purging inactive short living branches**. 
 
 ## Analysis Parameters
 
 These parameters enable PR analysis:
 
 | Parameter Name        | Description |
-| --------------------- | ------------------ |
-| `sonar.pullrequest.key` | Unique identifier of your PR. Must correspond to the key of the PR in GitHub or Azure DevOps. <br/> E.G.: `sonar.pullrequest.key=5` |
-| `sonar.pullrequest.branch` | The name of the branch that contains the changes to be merged.<br/> Ex: `sonar.pullrequest.branch=feature/my-new-feature`|
-| `sonar.pullrequest.base` | The long-lived branch into which the PR will be merged. <br/> Default: master <br/> E.G.: `sonar.pullrequest.base=master`|
-
-## PR Decoration
-This section details how to decorate your PRs with {instance} issues in your SCM provider's interface.
-
-### Specifying Your PR Provider
-
-Specify your PR provider in your global settings at [**Administration > General Settings > Pull Requests > General > Provider**](/#sonarqube-admin#/sonarqube/admin/settings?category=pull_request/). This is the name of the system managing your PR. When using the {instance} Extension for Azure DevOps, the provider is automatically populated.
-
-### GitHub Enterprise PR Decoration
-
-[[info]]
-| *Minimum GitHub Enterprise version* 2.14
-
-To add PR decoration to Checks on GitHub Enterprise, you need to create a GitHub App and configure your SonarQube instance and update your project-level settings.
-
-#### Creating Your GitHub App
-An instance administrator needs to create a GitHub App and configure your SonarQube instance. See [GitHub Enterprise Integration](/instance-administration/github-application/) for instructions.
-
-#### Updating Your GitHub Project Settings
-In your project settings, set your project repository identifier (for example, SonarSource/sonarqube) at **Administration > General Settings > Pull Requests > Integration with GitHub > Repository identifier**.
-
-### Bitbucket Server PR Decoration
-
-[[info]]
-| *Minimum BitBucket Server version* 5.15
-
-To add PR decoration on Bitbucket Server, you need to set a personal access token and update some settings. 
-
-#### Setting Your Personal Access Token
-
-In your global settings, set the personal access token of the user that will be used to decorate the PRs in the SonarQube UI:
-
-* Set the token at [**Administration > General Settings > Pull Requests > Integration with Bitbucket Server > Personal access token**](/#sonarqube-admin#/admin/settings?category=pull_request/)
-* The user that will be used to decorate PRs needs write permission.
-
-#### Updating Your Bitbucket Server Settings
-
-In your global settings, set your Bitbucket Server URL (for example, `https://myinstance.mycompany.com/`) at [**Administration > General Settings > Pull Requests > Integration with Bitbucket Server > The URL of the Bitbucket Server**](/#sonarqube-admin#/admin/settings?category=pull_request/). This is the base URL for your Bitbucket Server instance.
-
-In your project settings at **Administration > General Settings > Pull Requests > Integration with Bitbucket Server** update the following Bitbucket Server settings:
-
-* Bitbucket Server project key. You can find it in the Bitbucket Server repository URL (.../projects/**{KEY}**/repos/{SLUG}/browse).
-For projects in a personal space, the project key is "~" followed by your username (for example,  `~YourUsername`).
-* Bitbucket Server repository slug. You can find it in the Bitbucket Server repository URL (.../projects/{KEY}/repos/**{SLUG}**/browse).
-
-### Azure DevOps Server PR Decoration
-
-To add PR decoration on Azure DevOps Server, you need to set a personal access token.
-
-#### Setting Your Personal Access Token
-
-In global and project settings, set the personal access token of the user that will be used to decorate the PRs in the SonarQube UI at [**Administration > General Settings > Pull Requests > Integration with Azure DevOps > Personal access token**](/#sonarqube-admin#/admin/settings?category=pull_request/). 
-
-The user that will be used to decorate PRs needs to be authorized for the scope: 'Code (read and write)'.	
-
-### 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 > General](/#sonarqube-admin#/admin/settings)**) must be set correctly. Otherwise the links will default to `localhost`.
+| --------------------- | ---------------------------------- |
+| `sonar.pullrequest.key` | Unique identifier of your PR. Must correspond to the key of the PR in GitHub or Azure DevOps.<br/> e.g.: `sonar.pullrequest.key=5` |
+| `sonar.pullrequest.branch` | The name of the branch that contains the changes to be merged.<br/> e.g.: `sonar.pullrequest.branch=feature/my-new-feature` |
+| `sonar.pullrequest.base` | The long-lived branch into which the PR will be merged. <br/> Default: master <br/> e.g.: `sonar.pullrequest.base=master` |