Improve documentation

nhs-england-tools · Oct 31, 2023 · a31ddec · a31ddec
1 parent 804763c
commit a31ddec
Show file tree

Hide file tree

Showing 2 changed files with 13 additions and 8 deletions.
diff --git a/docs/adr/ADR-003_Acceptable_use_of_GitHub_PAT_and_Apps_for_authN_and_authZ.md b/docs/adr/ADR-003_Acceptable_use_of_GitHub_PAT_and_Apps_for_authN_and_authZ.md
@@ -2,7 +2,7 @@
 
 >|              | |
 >| ------------ | --- |
->| Date         | `11/09/2023` |
+>| Date         | `04/09/2023` |
 >| Status       | `RFC` |
 >| Deciders     | `Engineering` |
 >| Significance | `Construction techniques` |
@@ -136,7 +136,7 @@ This guide describes the essence of the fundamental aspects of GitHub authentica
 To be executed by a GitHub organisation administrator:
 
 - Identify the GitHub repository name for which the team has requested a GitHub App integration
-- Create a shared email address [england.[repository-name][email protected]](england.[repository-name][email protected]) by completing the `New shared mailbox request` form on the Internal Portal (ServiceNow). For programmes with multiple repositories, consider an alternative naming such as [england.[programme-name][email protected]](england.[programme-name][email protected])
+- Create a shared email address [england.[repository-name][email protected]](england.[repository-name][email protected]) by filling in the `New shared mailbox request` form using the Internal Portal (ServiceNow)
   - Delegate access to this mailbox for the GitHub organisation owners, administrators and the engineering team
 - Create a GitHub bot account named `[repository-name]-app` using the email address mentioned above. The bot account should not be added to the organisation; therefore, **no GitHub seat will be taken**. It serves as an identity, but authentication and authorisation are handled via the GitHub App. This avoids granting the bot admin permissions to the repository, enabling commits to be signed by that bot account. Access is controlled solely through the GitHub App.
   - Use the `nhs.net` email address as the default and only email

diff --git a/docs/user-guides/Perform_static_analysis.md b/docs/user-guides/Perform_static_analysis.md
@@ -5,7 +5,7 @@
   - [Key files](#key-files)
   - [Setup](#setup)
   - [Testing](#testing)
-  - [Configuration checklist for the GitHub Admins](#configuration-checklist-for-the-github-admins)
+  - [Configuration checklist](#configuration-checklist)
 
 ## Overview
 
@@ -22,7 +22,7 @@ Static code analysis is an essential part of modern software development. It pro
 
 ## Setup
 
-Contact the GitHub Admins via email to have your [SonarCloud](https://sonarcloud.io) access set up.
+Contact the GitHub Admins via their mailbox to have your [SonarCloud](https://sonarcloud.io) access set up.
 
 ## Testing
 
@@ -35,7 +35,10 @@ export SONAR_TOKEN=[replace-with-your-sonar-token]
 ./scripts/reports/perform-static-analysis.sh
 ```
 
-## Configuration checklist for the GitHub Admins
+## Configuration checklist
+
+> [!WARNING]<br>
+> This section is to be used by the the GitHub Admins.
 
 The list demonstrates the manual way of configuring a project, however our aim is to automate all the activities below.
 
@@ -66,13 +69,15 @@ The list demonstrates the manual way of configuring a project, however our aim i
 - 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)
-
-> [!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.