Incorporate feedback from an internal team

Author: stefaniuk

docs/adr/ADR-003_Acceptable_use_of_GitHub_PAT_and_Apps_for_authN_and_authZ.md

@@ -18,11 +18,12 @@
     - [Options](#options)
     - [Outcome](#outcome)
       - [Built-in authentication using `GITHUB_TOKEN` secret](#built-in-authentication-using-github_token-secret)
-      - [GitHub PAT (Personal Access Token)](#github-pat-personal-access-token)
+      - [GitHub PAT (fine-grained Personal Access Token)](#github-pat-fine-grained-personal-access-token)
       - [GitHub App](#github-app)
     - [Rationale](#rationale)
   - [Notes](#notes)
     - [GitHub App setup](#github-app-setup)
+      - [Recommendation for GitHub Admins](#recommendation-for-github-admins)
     - [Diagram](#diagram)
       - [Context diagram showing the GitHub App setup](#context-diagram-showing-the-github-app-setup)
       - [Authentication flow diagram](#authentication-flow-diagram)
@@ -61,21 +62,20 @@ There are three options available to support automated GitHub Action and Workflo
    - ➖ **The token can only access a repository containing the workflow file**. If you need to access other private repositories or require write access to other public repositories this token will not be sufficient.
    - ➖ **The token cannot trigger other workflows**. If you have a workflow that creates a release and another workflow that runs when someone creates a release, the first workflow will not trigger the second workflow if it utilises this token based mechanism for authentication.
 
-2. [GitHub PAT](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) (Personal Access Token)
+2. [GitHub PAT](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) (fine-grained Personal Access Token)
 
-   - ➕ **Simple to set up**. You can create a [fine-grained personal access token](https://github.com/settings/tokens?type=beta) with a repository scope or a [classic personal access token](https://github.com/settings/tokens) with a wider permission model that extends beyond a single repository.
+   - ➕ **Simple to set up**. You can create a [fine-grained personal access token](https://github.com/settings/tokens?type=beta) with a repository scope. Classic personal access token should never be used.
+   - ➕ **GitHub PAT provides a more fine-grained permission model** than the built-in `GITHUB_TOKEN`
    - ➕ **The token can trigger other workflows**.
-   - ➕ **It can access all repositories you have access to** (using a classic PAT). This is convenient because you can access other repositories without any additional setup.
-   - ➖ **It can access all your repositories you have access to** (using a classic PAT). You do not have fine-grained control over which repositories this token can access because this token represents you.
    - ➖ **It is bound to a person**. The owner of the token leaving the organisation can cause your workflow to break.
 
 3. [GitHub App](https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps)
 
    - ➕ **You can control which repositories your token has access to** by installing the GitHub App to selected repositories.
    - ➕ **An organisation can own multiple GitHub Apps** and they do not consume a team seat.
-   - ➕ **GitHub App provides a more fine-grained permission model**.
+   - ➕ **GitHub App provides a more fine-grained permission model** than the built-in `GITHUB_TOKEN`
    - ➕ **The token can trigger other workflows**.
-   - ➖ **Not very well documented**.
+   - ➖ **Not very well documented**. Despite the extensive content of the GitHub documentation, it does not effectively communicate the pros & cons, use-cases and comparison of each authentication method. This was one of the reasons we created this ADR.
    - ➖ **The setup is a bit more complicated**.
 
 ### Outcome
@@ -89,7 +89,7 @@ A `GITHUB_TOKEN` is automatically generated and used within GitHub Action and Wo
 
 This method <u>enables basic operations</u> expected from the repository pipeline, like accessing GitHub secret variables.
 
-#### GitHub PAT (Personal Access Token)
+#### GitHub PAT (fine-grained Personal Access Token)
 
 Use personal access token when:
 
@@ -117,7 +117,7 @@ Use app when:
 
 - **Acting on behalf of a user or an organisation**: GitHub Apps can be installed directly onto an organisation or a user account and can access specific repositories. They act as separate entities and do not need a specific user to authenticate actions, thus separating the app's actions from individual users and preventing user-related issues (like a user leaving the organisation) from disrupting the app's operation. In this model, a GitHub App can act on behalf of a user to perform actions that the user has permissions for. For example, if a GitHub App is used to manage issues in a repository, it can act on behalf of a user to open, close, or comment on issues. The actions the app can perform are determined by the user's permissions and the permissions granted to the app during its installation.
 
-- **When you need fine-grained permissions**: GitHub Apps provide more detailed control over permissions than the classic PAT. You can set access permissions on a per-resource basis (issues, pull requests, repositories, etc.). This allows you to follow the principle of least privilege, granting your app only the permissions it absolutely needs.
+- **When you need fine-grained permissions**: GitHub Apps provide more detailed control over permissions than the classic PAT, which should no longer be used. You can set access permissions on a per-resource basis (issues, pull requests, repositories, etc.). This allows you to follow the principle of least privilege, granting your app only the permissions it absolutely needs.
 
 - **Webhook events**: GitHub Apps can be configured to receive a variety of webhook events. Unlike personal tokens, apps can receive granular event data and respond accordingly. For instance, an app can listen for `push` events to trigger a CI/CD pipeline or `issue_comment` events to moderate comments.
 
@@ -156,6 +156,10 @@ To be executed by a GitHub organisation owner:
 
 - Install the `[Team] [Repository Name] [Purpose]` app on the GitHub organisation and set repository access to the `[repository-name]` only
 
+#### Recommendation for GitHub Admins
+
+It is advisable to create a separate bot account for each service or programme. This approach fosters responsible ownership practices. It also allows the team to use the bot's identity for signing commits and integrating their service with other SaaS products, such as SonarCloud, without relying on individual team member accounts. Exceptions can be made on a case-by-case basis, allowing for the use of a central organisation account instead.
+
 ### Diagram
 
 #### Context diagram showing the GitHub App setup
@@ -200,8 +204,6 @@ Please, see the above being implemented for the _update from template_ capabilit
 - [GitHub account (bot)](https://github.com/update-from-template-app) linked to an `nhs.net` email address, but not part of any GitHub organisation
 - [GitHub App (registration)](https://github.com/apps/nhs-england-update-from-template) to be installed within the GitHub organisations in use, e.g. `nhs-england-tools`
 
-<span style="color:red">A recommendation for GitHub Admins:</span> It is advisable to create a separate bot account for each service. This approach fosters responsible ownership practices. It also allows the team to use the bot's identity for signing commits and integrating their service with other SaaS products, such as SonarCloud, without relying on individual team member accounts. Exceptions can be made on a case-by-case basis, allowing for the use of a central organisation account instead.
-
 #### Authentication flow diagram
 
 The diagram below represents all the steps needed for an app implementation (aka app runner) to be authenticated and authorised to perform operations defined by the GitHub App registration and installation.

docs/user-guides/Perform_static_analysis.md

@@ -21,17 +21,18 @@ Static code analysis is an essential part of modern software development. It pro
 
 ## Configuration checklist
 
-- Create your [SonarCloud](https://sonarcloud.io) project
+- 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
 - 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, set the following properties according to the information provided above
-  - `sonar.[language].[coverage-tool].reportPaths` to ensure the unit test coverage is reported back to Sonar
+- 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
 - 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. Doing so will duplicate reports and initiate them outside the primary pipeline workflow
-- Confirm that the 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)
+- 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