SONAR-14399 Create Bitbucket Cloud PR decoration docs

diff --git a/server/sonar-docs/src/pages/analysis/bitbucket-cloud-integration.md b/server/sonar-docs/src/pages/analysis/bitbucket-cloud-integration.md
index 1d8a2baf73a54b351a1709b801350400b8b52a78..beddf0a7ddbba538511d59144704da1838f60d54 100644 (file)
--- a/server/sonar-docs/src/pages/analysis/bitbucket-cloud-integration.md
+++ b/server/sonar-docs/src/pages/analysis/bitbucket-cloud-integration.md
@@ -8,6 +8,7 @@ SonarQube's integration with Bitbucket Cloud allows you to maintain code quality
 With this integration, you'll be able to:
 
 - **Analyze projects with Bitbucket Pipelines** - Integrate analysis into your build pipeline. SonarScanners running in Bitbucket Pipelines can automatically detect branches or pull requests being built so you don't need to specifically pass them as parameters to the scanner (branch and pull request analysis is available starting in [Developer Edition](https://redirect.sonarsource.com/editions/developer.html)).
+- **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 Cloud so you know if it's safe to merge your changes.
 
 ## Analyzing projects with Bitbucket Pipelines
 SonarScanners running in Bitbucket Pipelines can automatically detect branches or pull requests being built so you don't need to specifically pass them as parameters to the scanner.
@@ -18,15 +19,15 @@ Set up your build according to your SonarQube edition:
 - **Community Edition** – Community Edition doesn't support multiple branches, so you should only analyze your main branch. You can restrict analysis to your main branch by using the `branches.master` pipeline in your `bitbucket-pipelines.yml` file and not using the `pull-requests` pipeline.
 - **Developer Edition and above** – Bitbucket Pipelines can build specific branches and pull requests if you use the `branches` and `pull-requests` pipelines as shown in the example configurations below.
 
-### Setting environment variables 
+### Setting environment variables
 You can set environment variables securely for all pipelines in Bitbucket Cloud's settings. See [User-defined variables](https://support.atlassian.com/bitbucket-cloud/docs/variables-and-secrets/#User-defined-variables) for more information.
 
 [[info]]
 | You may need to commit your `bitbucket-pipelines.yml` before being able to set environment variables for pipelines.
- 
+
 You need to set the following environment variables in Bitbucket Cloud for analysis:
- 
-- `SONAR_TOKEN` – Generate a SonarQube [token](/user-guide/user-token/) for Bitbucket Cloud and create a custom **secured** environment variable in Bitbucket Cloud with `SONAR_TOKEN` as the **Name** and the token you generated as the **Value**. 
+
+- `SONAR_TOKEN` – Generate a SonarQube [token](/user-guide/user-token/) for Bitbucket Cloud and create a custom **secured** environment variable in Bitbucket Cloud with `SONAR_TOKEN` as the **Name** and the token you generated as the **Value**.
 - `SONAR_HOST_URL` – Create a custom environment variable with `SONAR_HOST_URL` as the **Name** and your SonarQube server URL as the **Value**.
 
 ### Configuring your bitbucket-pipelines.yml file
@@ -82,7 +83,7 @@ Click the scanner you're using below to expand the example configuration:
 |   caches:
 |     sonar: ~/.sonar
 | ```
- 
+
 [[collapse]]
 | ## SonarScanner for Maven
 |
@@ -124,7 +125,7 @@ Click the scanner you're using below to expand the example configuration:
 
 [[collapse]]
 | ## SonarScanner CLI
-| 
+|
 | **Note:** A project key has to be provided through a `sonar-project.properties` file, or through the command line parameter. For more information, see the [SonarScanner](/analysis/scan/sonarscanner/) documentation.
 |
 | Write the following in your `bitbucket-pipelines.yml`:
@@ -161,3 +162,38 @@ Click the scanner you're using below to expand the example configuration:
 
 ### For more information
 For more information on configuring your build with Bitbucket Pipelines, see the [Configure bitbucket-pipelines.yml](https://support.atlassian.com/bitbucket-cloud/docs/configure-bitbucket-pipelinesyml/) documentation provided by Atlassian.
+
+## Adding Pull Request decoration to Bitbucket cloud
+
+Pull request decoration shows your Quality Gate and analysis metrics directly in Bitbucket Cloud. To set up pull request decoration, you need to do the following:
+
+1. Set up a dedicated OAuth consumer to decorate your pull requests.
+1. Set your global **ALM Integration** settings.
+1. Set your project-level **Pull Request Decoration** settings.
+
+[[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.
+
+### Setting up your OAuth consumer
+SonarQube uses a dedicated OAuth consumer to decorate pull requests. You need to create the OAuth consumer in your Bitbucket Cloud workspace settings and specify the following:
+
+- **Name** – the name of your OAuth consumer
+- **Callback URL** – Bitbucket Cloud requires this field, but it's not used by SonarQube so you can use any URL.
+- **This is a private consumer** – Your OAuth consumer needs to be private. Make sure this check box is selected.
+- **Permissions** – Grant **Read** access for the **Pull requests** permission.
+
+### Setting your global ALM Integration settings
+To set your global ALM Integration settings, navigate to **Administration > ALM Integrations**, select the **Bitbucket** tab, and select **Bitbucket Cloud** as the variant you want to configure. From here, specify the following settings:
+
+- **Configuration Name** (Enterprise and Data Center Edition only) – The name used to identify your GitHub configuration at the project level. Use something succinct and easily recognizable.
+- **Workspace ID** – The workspace ID is part of your bitbucket cloud URL `https://bitbucket.org/{WORKSPACE-ID}/{repository-slug}`
+- **OAuth Key** – Bitbucket automatically creates an OAuth key when you create your OAuth consumer. You can find it in your Bitbucket Cloud workspace settings under **OAuth consumers**.
+- **OAuth Secret** – Bitbucket automatically creates an OAuth secret when you create your OAuth consumer. You can find it in your Bitbucket Cloud workspace settings under **OAuth consumers**.
+
+### Setting your project-level Pull Request Decoration settings
+From your project **Overview**, navigate to **Project Settings > General Settings > Pull Request Decoration**.
+
+From here, set your:
+
+- **Configuration name** – The configuration name that corresponds to your Bitbucket Cloud instance.
+- **Repository SLUG** – The repository SLUG is part of your bitbucket cloud URL `https://bitbucket.org/{workspace-id}/{REPOSITORY-SLUG}`