Update documentation on setting up a SonarCloud project (nhs-england-…

…tools#122)

## Description

<!-- Describe your changes in detail. -->

## Context

<!-- Why is this change required? What problem does it solve? -->

## Type of changes

- [x] Refactoring (non-breaking change)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would change existing
functionality)
- [ ] Bug fix (non-breaking change which fixes an issue)

## Checklist

- [x] I am familiar with the [contributing
guidelines](../docs/CONTRIBUTING.md)
- [x] I have followed the code style of the project
- [ ] I have added tests to cover my changes
- [x] I have updated the documentation accordingly
- [ ] This PR is a result of pair or mob programming

---

## Sensitive Information Declaration

To ensure the utmost confidentiality and protect your and others
privacy, we kindly ask you to NOT including [PII (Personal Identifiable
Information) / PID (Personal Identifiable
Data)](https://digital.nhs.uk/data-and-information/keeping-data-safe-and-benefitting-the-public)
or any other sensitive data in this PR (Pull Request) and the codebase
changes. We will remove any PR that do contain any sensitive
information. We really appreciate your cooperation in this matter.

- [x] I confirm that neither PII/PID nor sensitive data are included in
this PR and the codebase changes.

---------

Signed-off-by: Alex Young <[email protected]>
Co-authored-by: Alex Young <[email protected]>

docs/user-guides/Perform_static_analysis.md

@@ -3,8 +3,9 @@
 - [Guide: Perform static analysis](#guide-perform-static-analysis)
   - [Overview](#overview)
   - [Key files](#key-files)
-  - [Configuration checklist](#configuration-checklist)
+  - [Setup](#setup)
   - [Testing](#testing)
+  - [Configuration checklist](#configuration-checklist)
 
 ## Overview
 
@@ -19,26 +20,64 @@ Static code analysis is an essential part of modern software development. It pro
 - [perform-static-analysis/action.yaml](../../.github/actions/perform-static-analysis/action.yaml): GitHub action to run the script as part of the CI/CD pipeline
 - [.gitignore](../../.gitignore): Excludes the `.scannerwork` temporary directory created during the process
 
+## Setup
+
+Contact the GitHub Admins via their mailbox to have your [SonarCloud](https://sonarcloud.io) access set up.
+
+## Testing
+
+You can run and test static analysis locally on a developer's workstation using the following command
+
+```shell
+export SONAR_ORGANISATION_KEY=nhs-england-tools # Replace with your organisation key
+export SONAR_PROJECT_KEY=repository-template # Replace with your project key
+export SONAR_TOKEN=[replace-with-your-sonar-token]
+./scripts/reports/perform-static-analysis.sh
+```
+
 ## Configuration checklist
 
-- Contact the GitHub Admins via email to have your [SonarCloud](https://sonarcloud.io) project created within the organisation space
-- Create a bot account for your service. For more details, please see this [note](../../docs/adr/ADR-003_Acceptable_use_of_GitHub_PAT_and_Apps_for_authN_and_authZ.md#recommendation-for-github-admins). This account should be given access to your project and must own the `SONAR_TOKEN` for security reasons. Use this account to complete the rest of the activities in the Sonar service
+> [!WARNING]<br>
+> This section is to be used by the GitHub Admins.
+
+The list demonstrates the manual way of configuring a project, however our aim is to automate all the activities below.
+
+- Create a Sonar project within the organisation space:
+  - Navigate to `+ > Analyze new project > create a project manually`
+  - Choose the appropriate organisation
+  - Set "Display name"
+  - Set "Project key" (it should be populated automatically)
+  - Set project visibility to "Public"
+  - After clicking the 'Next' button, set "The new code for this project will be based on" to "Previous version"
+  - Click "Create project"
+- Add two new groups under `Administration > Groups`:
+  - `[Programme Name]`, all members of the project
+  - `[Programme Name] Admins`, who will the project's quality gates and quality profiles
+- Assign members to the above groups accordingly
+- Set group permissions under `Administration > Permissions`:
+  - For the `[Programme Name] Admins` group, assign:
+    - "Quality Gates"
+    - "Quality Profiles"
+- Manage project permissions, navigate to `Administration > Projects Management` and select the project you created
+  - Click on `Edit Permissions`
+  - Search for `[Programme Name] Admins` group and assign the following:
+    - "Administer Issues"
+    - "Administer Security Hotspots"
+    - "Administer"
+    - Ensure that other groups do not have unnecessary permissions to administer this project
 - Navigate to project `Administration > Analysis Method > Manually` and select `Other (for JS, TS, Go, Python, PHP, ...)`
 - In the [sonar-scanner.properties](../../scripts/config/sonar-scanner.properties) file in your repository, set the following properties according to the information provided above
   - Set `sonar.[language].[coverage-tool].reportPaths` to ensure the unit test coverage is reported back to Sonar
   - Do not set the `sonar.organization` and `sonar.projectKey` properties in this file; do the next step instead
+
+- Use the Sonar token owned by the "SonarCloud Token GitHub Admins" service user. There is an existing token named "Scan all"
+
+> [!NOTE]<br>
+> For an advance configuration create a bot account for your service. For more details, please see this [note](../../docs/adr/ADR-003_Acceptable_use_of_GitHub_PAT_and_Apps_for_authN_and_authZ.md#recommendation-for-github-admins). This account should be given access to your project and must own the `SONAR_TOKEN` for security reasons.
+
 - Follow the documentation on [creating encrypted secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets) to add the `SONAR_TOKEN` secret to your repository. The GitHub action is already configured to fetch that secret and pass it as a variable. In addition to that:
   - Add `SONAR_ORGANISATION_KEY` variable (not a secret)
   - Add `SONAR_PROJECT_KEY` variable (not a secret)
 - Navigate to project `Administration > Analysis Method` and turn off the `Automatic Analysis` option
 - Please refrain from adding your repository to the GitHub SonarCloud App, as this app should not be used. Doing so will duplicate reports and initiate them outside the primary pipeline workflow
 - Confirm that the _"Perform static analysis"_ GitHub action is part of your GitHub CI/CD workflow and enforces the _"Sonar Way"_ quality gates. You can find more information about this in the [NHSE Software Engineering Quality Framework](https://github.com/NHSDigital/software-engineering-quality-framework/blob/main/tools/sonarqube.md)
-
-## Testing
-
-You can run and test static analysis locally on a developer's workstation using the following command
-
-```shell
-export SONAR_TOKEN=[replace-with-your-sonar-token]
-./scripts/perform-static-analysis.sh
-```