Merge remote-tracking branch 'origin/main' into wip-lambda-tutorial-m…

…erge

.github/actions/check-markdown-format/action.yaml

@@ -7,4 +7,4 @@ runs:
       shell: bash
       run: |
         export BRANCH_NAME=origin/${{ github.event.repository.default_branch }}
-        ./scripts/githooks/check-markdown-format.sh
+        check=branch ./scripts/githooks/check-markdown-format.sh

.github/actions/cloc-repository/action.yaml → .github/actions/create-lines-of-code-report/action.yaml

@@ -26,16 +26,16 @@ runs:
       shell: bash
       run: |
         export BUILD_DATETIME=${{ inputs.build_datetime }}
-        ./scripts/reports/cloc-repository.sh
+        ./scripts/reports/create-lines-of-code-report.sh
     - name: "Compress CLOC report"
       shell: bash
-      run: zip cloc-report.json.zip cloc-report.json
+      run: zip lines-of-code-report.json.zip lines-of-code-report.json
     - name: "Upload CLOC report as an artefact"
       if: ${{ !env.ACT }}
       uses: actions/upload-artifact@v3
       with:
-        name: cloc-report.json.zip
-        path: ./cloc-report.json.zip
+        name: lines-of-code-report.json.zip
+        path: ./lines-of-code-report.json.zip
         retention-days: 21
     - name: "Check prerequisites for sending the report"
       shell: bash
@@ -53,5 +53,5 @@ runs:
       if: steps.check.outputs.secrets_exist == 'true'
       run: |
         aws s3 cp \
-          ./cloc-report.json.zip \
-          ${{ inputs.idp_aws_report_upload_bucket_endpoint }}/${{ inputs.build_timestamp }}-cloc-report.json.zip
+          ./lines-of-code-report.json.zip \
+          ${{ inputs.idp_aws_report_upload_bucket_endpoint }}/${{ inputs.build_timestamp }}-lines-of-code-report.json.zip

.github/actions/scan-dependencies/action.yaml

@@ -26,7 +26,7 @@ runs:
       shell: bash
       run: |
         export BUILD_DATETIME=${{ inputs.build_datetime }}
-        ./scripts/reports/generate-sbom.sh
+        ./scripts/reports/create-sbom-report.sh
     - name: "Compress SBOM report"
       shell: bash
       run: zip sbom-repository-report.json.zip sbom-repository-report.json

.github/actions/scan-secrets/action.yaml

@@ -6,5 +6,5 @@ runs:
     - name: "Scan secrets"
       shell: bash
       run: |
-        export ALL_FILES=true # Do not change this line, as new patterns may be added or history may be rewritten
-        ./scripts/githooks/scan-secrets.sh
+        # Please do not change this `check=whole-history` setting, as new patterns may be added or history may be rewritten.
+        check=whole-history ./scripts/githooks/scan-secrets.sh

.github/workflows/stage-1-commit.yaml

@@ -75,7 +75,7 @@ jobs:
         uses: actions/checkout@v4
       - name: "Lint Terraform"
         uses: ./.github/actions/lint-terraform
-  cloc-repository:
+  count-lines-of-code:
     name: "Count lines of code"
     runs-on: ubuntu-latest
     permissions:
@@ -86,7 +86,7 @@ jobs:
       - name: "Checkout code"
         uses: actions/checkout@v4
       - name: "Count lines of code"
-        uses: ./.github/actions/cloc-repository
+        uses: ./.github/actions/create-lines-of-code-report
         with:
           build_datetime: "${{ inputs.build_datetime }}"
           build_timestamp: "${{ inputs.build_timestamp }}"

.tool-versions

@@ -6,14 +6,15 @@ pre-commit 3.4.0
 # ==============================================================================
 # The section below is reserved for Docker image versions.
 
-# terraform, SEE: https://hub.docker.com/r/hashicorp/terraform/tags
-# docker/hashicorp/terraform 1.5.6@sha256:180a7efa983386a27b43657ed610e9deed9e6c3848d54f9ea9b6cb8a5c8c25f5
-
-# shellcheck, SEE: https://hub.docker.com/r/koalaman/shellcheck/tags
-# docker/koalaman/shellcheck latest@sha256:e40388688bae0fcffdddb7e4dea49b900c18933b452add0930654b2dea3e7d5c
-
-# hadolint, SEE: https://hub.docker.com/r/hadolint/hadolint/tags
-# docker/hadolint/hadolint 2.12.0-alpine@sha256:7dba9a9f1a0350f6d021fb2f6f88900998a4fb0aaf8e4330aa8c38544f04db42
-
-# ghcr.io/nhs-england-tools/github-runner-image, SEE: https://github.com/nhs-england-tools/github-runner-image/pkgs/container/github-runner-image
-# docker/ghcr.io/nhs-england-tools/github-runner-image 20230909-321fd1e-rt@sha256:ce4fd6035dc450a50d3cbafb4986d60e77cb49a71ab60a053bb1b9518139a646
+# TODO: Move this section - consider using a different file for the repository template dependencies.
+# docker/ghcr.io/anchore/grype v0.69.1@sha256:d41fcb371d0af59f311e72123dff46900ebd6d0482391b5a830853ee4f9d1a76 # SEE: https://github.com/anchore/grype/pkgs/container/grype
+# docker/ghcr.io/anchore/syft v0.92.0@sha256:63c60f0a21efb13e80aa1359ab243e49213b6cc2d7e0f8179da38e6913b997e0 # SEE: https://github.com/anchore/syft/pkgs/container/syft
+# docker/ghcr.io/gitleaks/gitleaks v8.18.0@sha256:fd2b5cab12b563d2cc538b14631764a1c25577780e3b7dba71657d58da45d9d9 # SEE: https://github.com/gitleaks/gitleaks/pkgs/container/gitleaks
+# docker/ghcr.io/igorshubovych/markdownlint-cli v0.37.0@sha256:fb3e79946fce78e1cde84d6798c6c2a55f2de11fc16606a40d49411e281d950d # SEE: https://github.com/igorshubovych/markdownlint-cli/pkgs/container/markdownlint-cli
+# docker/ghcr.io/make-ops-tools/gocloc latest@sha256:6888e62e9ae693c4ebcfed9f1d86c70fd083868acb8815fe44b561b9a73b5032 # SEE: https://github.com/make-ops-tools/gocloc/pkgs/container/gocloc
+# docker/ghcr.io/nhs-england-tools/github-runner-image 20230909-321fd1e-rt@sha256:ce4fd6035dc450a50d3cbafb4986d60e77cb49a71ab60a053bb1b9518139a646 # SEE: https://github.com/nhs-england-tools/github-runner-image/pkgs/container/github-runner-image
+# docker/hadolint/hadolint 2.12.0-alpine@sha256:7dba9a9f1a0350f6d021fb2f6f88900998a4fb0aaf8e4330aa8c38544f04db42 # SEE: https://hub.docker.com/r/hadolint/hadolint/tags
+# docker/hashicorp/terraform 1.5.6@sha256:180a7efa983386a27b43657ed610e9deed9e6c3848d54f9ea9b6cb8a5c8c25f5 # SEE: https://hub.docker.com/r/hashicorp/terraform/tags
+# docker/koalaman/shellcheck latest@sha256:e40388688bae0fcffdddb7e4dea49b900c18933b452add0930654b2dea3e7d5c # SEE: https://hub.docker.com/r/koalaman/shellcheck/tags
+# docker/mstruebing/editorconfig-checker 2.7.1@sha256:dd3ca9ea50ef4518efe9be018d669ef9cf937f6bb5cfe2ef84ff2a620b5ddc24 # SEE: https://hub.docker.com/r/mstruebing/editorconfig-checker/tags
+# docker/sonarsource/sonar-scanner-cli 5.0.1@sha256:494ecc3b5b1ee1625bd377b3905c4284e4f0cc155cff397805a244dee1c7d575 # SEE: https://hub.docker.com/r/sonarsource/sonar-scanner-cli/tags

README.md

@@ -43,12 +43,14 @@ cd nhs-england-tools/repository-template
 
 ### Prerequisites
 
-The following software packages, or their equivalents, are expected to be installed:
+The following software packages, or their equivalents, are expected to be installed and configured:
 
 - [docker](https://www.docker.com/) container runtime or a compatible tool, e.g. [podman](https://podman.io/),
 - [asdf](https://asdf-vm.com/) version manager,
 - [GNU make](https://www.gnu.org/software/make/) 3.82 or later,
-- [GNU coreutils](https://www.gnu.org/software/coreutils/) and [GNU binutils](https://www.gnu.org/software/binutils/) may be required to build dependencies like Python, which may need to be compiled during installation. For macOS users, this has been scripted and automated by the `dotfiles` project; please see this [script](https://github.com/nhs-england-tools/dotfiles/blob/main/assets/20-install-base-packages.macos.sh) for details.
+- [GNU coreutils](https://www.gnu.org/software/coreutils/) and [GNU binutils](https://www.gnu.org/software/binutils/) may be required to build dependencies like Python, which may need to be compiled during installation. For macOS users, this has been scripted and automated by the `dotfiles` project; please see this [script](https://github.com/nhs-england-tools/dotfiles/blob/main/assets/20-install-base-packages.macos.sh) for details,
+- [Python](https://www.python.org/) required to run Git hooks,
+- [jq](https://jqlang.github.io/jq/) a lightweight and flexible command-line JSON processor.
 
 > [!NOTE]<br>
 > The version of GNU make available by default on macOS is earlier than 3.82. You will need to upgrade it or certain `make` tasks will fail. On macOS, you will need [homebrew](https://brew.sh/) installed, then to install `make`, like so:

docs/adr/ADR-001_Use_git_hook_and_GitHub_action_to_check_the_editorconfig_compliance.md

@@ -136,7 +136,7 @@ Both, the git hook and the GitHub Action should be executed automatically as par
 
 ## Notes
 
-There is an emerging practice to use projects like [act](https://github.com/nektos/act) to make GitHub Actions even more portable. ~~The recommendation is for this tool to be assessed at further stages of the [nhs-england-tools/repository-template](https://github.com/nhs-england-tools/repository-template) project implementation, in the context of this decision record.~~ Update: Please, see the [Test GitHub Actions locally](../user-guides/Test_GitHub_Actions_locally.md) user guide.
+There is an emerging practice to use projects like [act](https://github.com/nektos/act) to make GitHub Actions even more portable. ~~The recommendation is for this tool to be assessed at further stages of the [nhs-england-tools/repository-template](https://github.com/nhs-england-tools/repository-template) project implementation, in the context of this decision record.~~ Update: Please see the [Test GitHub Actions locally](../user-guides/Test_GitHub_Actions_locally.md) user guide.
 
 ## Actions
 

docs/adr/ADR-003_Acceptable_use_of_GitHub_PAT_and_Apps_for_authN_and_authZ.md

@@ -198,7 +198,7 @@ C4Context
   }
 ```
 
-Please, see the above being implemented for the _update from template_ capability:
+Please see the above being implemented for the _update from template_ capability:
 
 - [Repository and GitHub App (runner)](https://github.com/nhs-england-tools/update-from-template-app) for the "Update from Template" app. The runner is built on a GitHub Action but it can be a serverless workload or self-hosted compute
 - [GitHub account (bot)](https://github.com/update-from-template-app) linked to an `nhs.net` email address, but not part of any GitHub organisation

docs/adr/ADR-XXX_Agree_CICD_pipeline_structure.md

@@ -26,7 +26,7 @@
 
 ## Context
 
-Describe the context and the problem statement. Is there a relationship to other decisions previously made? Are there any dependencies and/or constraints within which the decision will be made? Do these need to be reviewed or validated? Please, note that environmental limitations or restrictions such as accepted technology standards, commonly recognised and used patterns, engineering and architecture principles, organisation policies, governance and so on, may as an effect narrow down the choices. This should also be explicitly documented, as this is a point-in-time decision with the intention of being able to articulate it clearly and justify it later.
+Describe the context and the problem statement. Is there a relationship to other decisions previously made? Are there any dependencies and/or constraints within which the decision will be made? Do these need to be reviewed or validated? Please note that environmental limitations or restrictions such as accepted technology standards, commonly recognised and used patterns, engineering and architecture principles, organisation policies, governance and so on, may as an effect narrow down the choices. This should also be explicitly documented, as this is a point-in-time decision with the intention of being able to articulate it clearly and justify it later.
 
 Requirements:
 

docs/adr/ADR-nnn_Any_Decision_Record_Template.md

@@ -26,7 +26,7 @@
 
 ## Context
 
-Describe the context and the problem statement. Is there a relationship to other decisions previously made? Are there any dependencies and/or constraints within which the decision will be made? Do these need to be reviewed or validated? Please, note that environmental limitations or restrictions such as accepted technology standards, commonly recognised and used patterns, engineering and architecture principles, organisation policies, governance and so on, may as an effect narrow down the choices. This should also be explicitly documented, as this is a point-in-time decision with the intention of being able to articulate it clearly and justify it later.
+Describe the context and the problem statement. Is there a relationship to other decisions previously made? Are there any dependencies and/or constraints within which the decision will be made? Do these need to be reviewed or validated? Please note that environmental limitations or restrictions such as accepted technology standards, commonly recognised and used patterns, engineering and architecture principles, organisation policies, governance and so on, may as an effect narrow down the choices. This should also be explicitly documented, as this is a point-in-time decision with the intention of being able to articulate it clearly and justify it later.
 
 ## Decision
 

docs/adr/assets/ADR-003/examples/bash/script.sh

@@ -17,7 +17,7 @@ function main() {
 function get-jwt-token() {
 
   header=$(echo -n '{"alg":"RS256","typ":"JWT"}' | base64 | tr -d '=' | tr -d '\n=' | tr -- '+/' '-_')
-  payload=$(echo -n '{"iat":'$(date +%s)',"exp":'$(($(date +%s)+600))',"iss":"'$GITHUB_APP_ID'"}' | base64 | tr -d '\n=' | tr -- '+/' '-_')
+  payload=$(echo -n '{"iat":'"$(date +%s)"',"exp":'$(($(date +%s)+600))',"iss":"'"$GITHUB_APP_ID"'"}' | base64 | tr -d '\n=' | tr -- '+/' '-_')
   signature=$(echo -n "$header.$payload" | openssl dgst -binary -sha256 -sign "$GITHUB_APP_PK_FILE" | openssl base64 | tr -d '\n=' | tr -- '+/' '-_')
 
   echo "$header.$payload.$signature"
@@ -30,17 +30,17 @@ function get-installation-id() {
     -H "Accept: application/vnd.github.v3+json" \
     https://api.github.com/app/installations)
 
-  echo "$(echo $installations_response | jq '.[] | select(.account.login == "'"$GITHUB_ORG"'") .id')"
+  echo "$installations_response" | jq '.[] | select(.account.login == "'"$GITHUB_ORG"'") .id'
 }
 
 function get-access-token() {
 
   token_response=$(curl -sX POST \
     -H "Authorization: Bearer $jwt_token" \
     -H "Accept: application/vnd.github.v3+json" \
-    https://api.github.com/app/installations/$installation_id/access_tokens)
+    "https://api.github.com/app/installations/$installation_id/access_tokens")
 
-  echo "$(echo $token_response | jq .token -r)"
+  echo "$token_response" | jq .token -r
 }
 
 main

docs/adr/assets/ADR-003/examples/golang/go.mod

@@ -7,4 +7,4 @@ require (
 	github.com/golang-jwt/jwt v3.2.2+incompatible
 )
 
-require golang.org/x/net v0.7.0 // indirect
+require golang.org/x/net v0.17.0 // indirect

docs/adr/assets/ADR-003/examples/golang/go.sum

@@ -3,8 +3,8 @@ github.com/go-resty/resty/v2 v2.7.0/go.mod h1:9PWDzw47qPphMRFfhsyk0NnSgvluHcljSM
 github.com/golang-jwt/jwt v3.2.2+incompatible h1:IfV12K8xAKAnZqdXVzCZ+TOjboZ2keLg81eXfW3O+oY=
 github.com/golang-jwt/jwt v3.2.2+incompatible/go.mod h1:8pz2t5EyA70fFQQSrl6XZXzqecmYZeUEB8OUGHkxJ+I=
 golang.org/x/net v0.0.0-20211029224645-99673261e6eb/go.mod h1:9nx3DQGgdP8bBQD5qxJ1jj9UTztislL4KSBs9R2vV5Y=
-golang.org/x/net v0.7.0 h1:rJrUqqhjsgNp7KqAIc25s9pZnjU7TUcSY7HcVZjdn1g=
-golang.org/x/net v0.7.0/go.mod h1:2Tu9+aMcznHK/AK1HMvgo6xiTLG5rD5rZLDS+rp2Bjs=
+golang.org/x/net v0.17.0 h1:pVaXccu2ozPjCXewfr1S7xza/zcXTity9cCdXQYSjIM=
+golang.org/x/net v0.17.0/go.mod h1:NxSsAGuq816PNPmqtQdLE42eU2Fs7NoRIZrHJAlaCOE=
 golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210423082822-04245dca01da/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=

docs/developer-guides/Bash_and_Make.md

@@ -19,7 +19,7 @@ some-target: # Target description - mandatory: foo=[description]; optional: baz=
 
 - `some-target`: This is the name of the target you would specify when you want to run this particular target. Use the kebab-case naming convention and prefix with an underscore `_` to mark it as a "private" target. The first part of the name is used for grouping, e.g. `docker-*` or `terraform-*`.
 - `Target Description`: Provided directly after the target name as a single line, so be concise.
-- `mandatory` parameters: Parameters that must be provided when invoking the target. Each parameter has its own description. Please, follow the specified format as it is used by `make help`.
+- `mandatory` parameters: Parameters that must be provided when invoking the target. Each parameter has its own description. Please follow the specified format as it is used by `make help`.
 - `optional` parameters: Parameters that are not required when invoking the target. They may have a default value. Each parameter has its own description.
 - `@Category` label: Used for grouping by the `make help` command.
 - `Recipe implementation`: This section defines the actual commands or steps the target will execute. **Do not exceed 5 lines of effective code**. For more complex operations, use a shell script. Refer to the `docker-build` implementation in the [docker.mk](../../scripts/docker/docker.mk) file. More complex operations are implemented in the [docker.sh](../../scripts/docker/docker.lib.sh) script for readability and simplicity.
@@ -140,7 +140,7 @@ VERBOSE=1 scripts/shellscript-linter.sh
 
 ### Scripts
 
-Most scripts provided with this repository template can utilise tools installed on your `PATH` if they are available or run them from within a Docker container. To force a script to use Docker, the `FORCE_USE_DOCKER` variable is provided. Here is an example of how to use it:
+Most scripts provided with this repository template can utilise tools installed on your `PATH` if they are available or run them from within a Docker container. To force a script to use Docker, the `FORCE_USE_DOCKER` variable is provided. This feature increases configurability of the development environment, allowing you to use custom tooling by default if present on the command-line path. Here is an example of how to use it:
 
 ```shell
 FORCE_USE_DOCKER=1 scripts/shellscript-linter.sh

docs/user-guides/Perform_static_analysis.md

@@ -31,7 +31,7 @@ Static code analysis is an essential part of modern software development. It pro
   - 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
+- 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

docs/user-guides/Scan_dependencies.md

@@ -15,7 +15,7 @@ In modern software development, leveraging third-party dependencies is a common
 
 ## Key files
 
-- [generate-sbom.sh](../../scripts/reports/generate-sbom.sh): A shell script that generates SBOM (Software Bill of Materials)
+- [create-sbom-report.sh](../../scripts/reports/create-sbom-report.sh): A shell script that generates SBOM (Software Bill of Materials)
 - [syft.yaml](../../scripts/config/syft.yaml): A configuration file for the SBOM generator
 - [scan-vulnerabilities.sh](../../scripts/reports/scan-vulnerabilities.sh): A shell script that performs CVE analysis
 - [grype.yaml](../../scripts/config/grype.yaml): A configuration file for the CVE scanner
@@ -41,7 +41,7 @@ You can run and test the process locally on a developer's workstation using the
 SBOM generator
 
 ```shell
-./scripts/reports/generate-sbom.sh
+./scripts/reports/create-sbom-report.sh
 cat sbom-repository-report.json | jq
 ```
 
@@ -70,4 +70,4 @@ cat vulnerabilities-repository-reportc.json | jq
    - Easier investigation of CVEs found in the repository, eliminating dependence on a third party like GitHub
    - Enhanced portability and flexibility, allowing the scans to run in diverse environments
 
-   However, this approach should be periodically reviewed as there is an emerging practice to use projects like [act](https://github.com/nektos/act) ~~to make GitHub Actions portable~~. Update: Please, see the [Test GitHub Actions locally](../user-guides/Test_GitHub_Actions_locally.md) user guide.
+   However, this approach should be periodically reviewed as there is an emerging practice to use projects like [act](https://github.com/nektos/act) ~~to make GitHub Actions portable~~. Update: Please see the [Test GitHub Actions locally](../user-guides/Test_GitHub_Actions_locally.md) user guide.