SONAR-14406 Update Bitbucket Server integration page

diff --git a/server/sonar-docs/src/pages/analysis/bitbucket-integration.md b/server/sonar-docs/src/pages/analysis/bitbucket-integration.md
index 42f1072bd9ae0c2a9d546a13d55b2f40ca49819f..c9684da2693ca82077e32b428d22842345584835 100644 (file)
--- a/server/sonar-docs/src/pages/analysis/bitbucket-integration.md
+++ b/server/sonar-docs/src/pages/analysis/bitbucket-integration.md
@@ -6,14 +6,14 @@ SonarQube's integration with Bitbucket Server allows you to maintain code qualit
 
 With this integration, you'll be able to:
 
-- **Import your BitBucket repositories** - (starting in [Developer Edition](https://redirect.sonarsource.com/editions/developer.html)) Import your Bitbucket repositories into SonarQube to easily set up SonarQube projects.  
-- **Add pull request decoration** - (starting in [Developer Edition](https://redirect.sonarsource.com/editions/developer.html)) See your Quality Gate and code metric results right in Bitbucket so you know if it's safe to merge your changes.
+- **Import your BitBucket Server repositories** - Import your Bitbucket Server repositories into SonarQube to easily set up SonarQube projects.  
+- **Add pull request decoration** - (starting in [Developer Edition](https://redirect.sonarsource.com/editions/developer.html)) See your Quality Gate and code metric results right in Bitbucket Server so you know if it's safe to merge your changes.
 
 ## Prerequisites
-- Integration with Bitbucket Server requires at least Bitbucket Server version 5.15.
+Integration with Bitbucket Server requires at least Bitbucket Server version 5.15.
 
 ## Importing your Bitbucket Server repositories into SonarQube
-Setting up the import of BitBucket Server repositories into SonarQube allows you to easily create SonarQube projects from your Bitbucket Server repositories. This is also the first step in adding pull request decoration.
+Setting up the import of BitBucket Server repositories into SonarQube allows you to easily create SonarQube projects from your Bitbucket Server repositories. If you're using [Developer Edition](https://redirect.sonarsource.com/editions/developer.html) or above, this is also the first step in adding pull request decoration.
 
 To set up the import of BitBucket Server repositories:
 
@@ -28,13 +28,11 @@ To import your Bitbucket Server projects into SonarQube, you need to first set y
 - **Personal Access Token** – A Bitbucket Server user account is used to decorate Pull Requests. We recommend using a dedicated Bitbucket Server account with Administrator permissions. 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. This personal access token is used for pull request decoration, and you'll be asked for another personal access token for importing projects in the following section.
 
 ### Adding a personal access token for importing repositories
-After setting these global settings, you can add a project from Bitbucket Server by clicking the "+" in the upper-right corner and selecting **Bitbucket**:
-
-![import a Bitbucket project](/images/add-bitbucket-project.png)
+After setting your global settings, you can add a project from Bitbucket Server by clicking the **Add project** button in the upper-right corner of the **Projects** homepage and selecting **Bitbucket**.
 
 Then, you'll be asked to provide a personal access token from your user account with `Read` permissions for both projects and repositories. This token will be stored in SonarQube and can be revoked at anytime in Bitbucket Server.
 
-After saving your Personal Access Token, you'll see a list of your Bitbucket Server projects that you can **set up** to add them to SonarQube. Setting up your projects this way also sets your project settings for pull request decoration.
+After saving your personal access token, you'll see a list of your Bitbucket Server projects that you can **set up** to add them to SonarQube. Setting up your projects this way also sets your project settings for pull request decoration.
 
 ## Adding pull request decoration to Bitbucket Server
 Pull request decoration shows your Quality Gate and analysis metrics directly in Bitbucket Server:
@@ -44,12 +42,12 @@ Pull request decoration shows your Quality Gate and analysis metrics directly in
 [[info]]
 | To decorate Pull Requests, a SonarQube analysis needs to be run on your code. You can find the additional parameters required for Pull Request analysis on the [Pull Request Analysis](/analysis/pull-request/) page.
 
-After you've set up SonarQube to import your Bitbucket Server repositories as shown in the previous section, the simplest way to add pull request decoration is by adding a project from Bitbucket Server by clicking the "+" in the upper-right corner and selecting **Bitbucket**.
+After you've set up SonarQube to import your Bitbucket Server repositories as shown in the previous section, the simplest way to add pull request decoration is by adding a project from Bitbucket Server by clicking the **Add project** button in the upper-right corner of the **Projects** homepage and selecting **Bitbucket**.
 
 Then, follow the steps in SonarQube to analyze your project. The project settings for pull request decoration are set automatically.
 
 ### Adding pull request decoration to a manually created or existing project
-To add pull request decoration to a manually created or existing project, after you've created and installed your GitHub App and updated your global ALM Integration settings as shown above, set your project settings at **Project Settings > General Settings > Pull Request Decoration**. 
+To add pull request decoration to a manually created or existing project, after you've updated your global ALM Integration settings as shown above, set your project settings at **Project Settings > General Settings > Pull Request Decoration**. 
 
 From here, set your: 
 
@@ -60,7 +58,25 @@ From here, set your:
 ### Advanced pull request decoration configuration
 
 [[collapse]]
-| ## **Configuring multiple ALM instances**
+| ## Adding pull request decoration to projects that are part of a mono repository
+|
+| In a mono repository setup, multiple SonarQube projects, each corresponding to a separate mono repository project, are all bound to the same repository. You'll need to set up pull request decoration for each SonarQube project.
+|
+| In Developer Edition, analyzing a pull request for a project that is part of a mono repository will override the current pull request decoration even if you're analyzing a different project.
+|
+| In [Enterprise Edition](https://redirect.sonarsource.com/editions/enterprise.html) and above, you can show pull request decoration for multiple projects simultaneously. 
+|
+| To do this, set your global ALM Integration settings as shown in the **Importing your Bitbucket Server repositories into SonarQube** section above, and set your project settings at **Project Settings > General Settings > Pull Request Decoration**.
+|
+| From here, set your: 
+|
+| - **Configuration name** – The configuration name that corresponds to your ALM instance.
+| - **Project Key** – Part of your BitBucket Server repository URL (.../projects/**{KEY}**/repos/{SLUG}/browse).
+| - **Repo Slug** – Part of your BitBucket Server repository URL (.../projects/{KEY}/repos/**{SLUG}**/browse).
+| - **Enable mono repository support** – (Enterprise Edition and above only) Set this to true  
+
+[[collapse]]
+| ## Configuring multiple ALM instances
 |You can decorate pull requests from multiple ALM instances by creating a configuration for each ALM instance and then assigning that instance configuration to the appropriate projects. 
 |
 |- As part of [Developer Edition](https://redirect.sonarsource.com/editions/developer.html), you can create one configuration for each ALM. 
@@ -68,5 +84,16 @@ From here, set your:
 |- Starting in [Enterprise Edition](https://redirect.sonarsource.com/editions/enterprise.html), you can create multiple configurations for each ALM. If you have multiple configurations of the same ALM connected to SonarQube, you have to create projects manually.
 
 [[collapse]]
-| ## **Linking issues**
+| ## Linking issues
 | During pull request decoration, individual issues will be linked to their SonarQube counterparts automatically. For this to work correctly, you need to set the instance's **Server base URL** (**[Administration > Configuration > General Settings > General > General](/#sonarqube-admin#/admin/settings/)**) correctly. Otherwise, the links will default to `localhost`.
+
+## Preventing pull request merges when the Quality Gate fails
+After setting up pull request analysis, you can block pull requests from being merged if it is failing the Quality Gate. To do this:
+1. In Bitbucket Server, navigate to **Repository settings > Code Insights**.
+2. Add a **Required report** called `com.sonarsource.sonarqube`
+
+[[info]]
+|If your SonarQube project is configured as part of a mono repository in Enterprise Edition or above, you need to use a **Required report** that uses a SonarQube project key (`com.sonarsource.sonarqube_{sq-project-key}` instead of `com.sonarsource.sonarqube`).
+
+3. Select **Must pass** as the **Required status**.
+4. Select **Must not have any annotations** as the **Annotation requirements**.