Chwa1 sort dist (#235)

<!-- markdownlint-disable-next-line first-line-heading -->
## Description

dist/ folder is not getting checked in

## Context

Currently calls for this action are failing

## Type of changes

<!-- What types of changes does your code introduce? Put an `x` in all
the boxes that apply. -->

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

## Checklist

<!-- Go over all the following points, and put an `x` in all the boxes
that apply. -->

- [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.

Author: walteck

.github/workflows/cicd-1-pull-request.yaml

@@ -9,11 +9,33 @@ on:
   pull_request:
     types: [opened, reopened]
 
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write
+  id-token: write
+
 jobs:
+  guard-dist:
+    name: "Guard: prevent committed dist changes"
+    runs-on: ubuntu-latest
+    steps:
+      - name: "Checkout code"
+        uses: actions/checkout@v4
+      - name: "Fail if dist/ contains changes"
+        run: |
+          if git ls-files --error-unmatch dist 2>/dev/null; then
+            echo "dist/ directory is committed. This repository expects dist to be added only by release automation." >&2
+            echo "Remove dist/ changes from your PR. They will be generated during release." >&2
+            exit 1
+          else
+            echo "No committed dist/ directory detected. Proceeding.";
+          fi
   metadata:
     name: "Set CI/CD metadata"
     runs-on: ubuntu-latest
     timeout-minutes: 1
+    needs: [guard-dist]
     outputs:
       build_datetime_london: ${{ steps.variables.outputs.build_datetime_london }}
       build_datetime: ${{ steps.variables.outputs.build_datetime }}
@@ -27,11 +49,25 @@ jobs:
     steps:
       - name: "Checkout code"
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: "Set up Node.js"
+        uses: actions/setup-node@v4
+        with:
+          node-version: 16
+          cache: npm
+      - name: "Install dependencies"
+        run: npm ci
+      - name: "Build action bundle (dry-run context)"
+        run: npm run package
       - name: "Semantic Release"
         uses: cycjimmy/semantic-release-action@v4.1.1
         id: semantic
         with:
           dry_run: true
+          extra_plugins: |
+            @semantic-release/git
+            @semantic-release/npm
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - name: "Set CI/CD variables"

.github/workflows/cicd-2-publish.yaml

@@ -6,6 +6,11 @@ on:
     branches: [ "main" ]
     types: ["completed"]
 
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+
 jobs:
   metadata:
     name: "Set CI/CD metadata"
@@ -50,13 +55,77 @@ jobs:
     steps:
       - name: "Checkout code"
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: "Generate GitHub App token"
+        uses: actions/create-github-app-token@v1
+        id: app-token
+        with:
+          app-id: ${{ secrets.APP_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+      - name: "Import GPG key and configure signing"
+        if: ${{ secrets.APP_SIGNING_KEY != '' }}
+        env:
+          APP_SIGNING_KEY: ${{ secrets.APP_SIGNING_KEY }}
+          GPG_KEY_ID: ${{ secrets.APP_SIGNING_KEY_ID }}
+          APP_SIGNING_KEY_PASSPHRASE: ${{ secrets.APP_SIGNING_KEY_PASSPHRASE }}
+        run: |
+          # Import the GPG signing key
+          echo "$APP_SIGNING_KEY" | gpg --batch --import
+
+          # Mark repository as safe (defensive measure for git operations)
+          git config --global --add safe.directory "$GITHUB_WORKSPACE"
+
+          # Configure git identity (will show as GitHub App)
+          git config --global user.name "notify-msteams-action release bot"
+          git config --global user.email "noreply@github.com"
+
+          # Configure commit signing with custom GPG wrapper (from repository)
+          git config --global user.signingkey "$GPG_KEY_ID"
+          git config --global commit.gpgsign true
+          git config --global tag.gpgSign true
+          git config --global gpg.program "$GITHUB_WORKSPACE/scripts/gpg-wrapper.sh"
+
+          # Configure GPG for non-interactive mode
+          mkdir -p ~/.gnupg
+          echo 'pinentry-mode loopback' >> ~/.gnupg/gpg.conf
+          echo 'allow-loopback-pinentry' >> ~/.gnupg/gpg-agent.conf || true
+          chmod 700 ~/.gnupg
+
+          # Set GPG_TTY for terminal interaction
+          export GPG_TTY=$(tty)
+
+          # Log key fingerprint for audit (not the key itself)
+          gpg --list-keys --with-colons | awk -F: '/^fpr/ {print "Using GPG key: " $10; exit}'
+      - name: "Set up Node.js"
+        uses: actions/setup-node@v4
+        with:
+          node-version: 16
+          cache: npm
+      - name: "Install dependencies"
+        run: npm ci
+      - name: "Build action bundle"
+        run: npm run package
       - name: "Semantic Release"
         uses: cycjimmy/semantic-release-action@v4.1.1
         id: semantic
         with:
           dry_run: ${{github.event_name == 'pull_request'}}
+          extra_plugins: |
+            @semantic-release/git
+            @semantic-release/npm
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
+      - name: "Update major tag"
+        if: steps.semantic.outputs.new_release_published == 'true'
+        run: |
+          version="${{ steps.semantic.outputs.new_release_version }}"
+          major_tag="v${version%%.*}"
+          git config user.name "github-actions"
+          git config user.email "github-actions@users.noreply.github.com"
+          git fetch --tags origin
+          git tag -f "${major_tag}" "v${version}"
+          git push origin -f "${major_tag}"
       - name: "Output new release details"
         if: steps.semantic.outputs.new_release_published == 'true'
         run: |

.gitleaksignore

@@ -1,3 +1,4 @@
 # SEE: https://github.com/gitleaks/gitleaks/blob/master/README.md#gitleaksignore
 
 cd9c0efec38c5d63053dd865e5d4e207c0760d91:docs/guides/Perform_static_analysis.md:generic-api-key:37
+a1b549dd793a0aa43eddc53455d6e08c6f8ab37f:docs/developer-guides/Release_Signing_and_GitHub_App.md:generic-api-key:146

.releaserc

@@ -1,10 +1,22 @@
 {
+  "branches": ["main"],
+  "tagFormat": "v${version}",
   "plugins": [
     "@semantic-release/commit-analyzer",
     "@semantic-release/release-notes-generator",
+    ["@semantic-release/changelog", { "changelogFile": "CHANGELOG.md" }],
+    ["@semantic-release/npm", { "npmPublish": false }],
+    ["@semantic-release/git", {
+      "assets": [
+        "CHANGELOG.md",
+        "package.json",
+        "package-lock.json",
+        "dist/**",
+        "licenses.txt",
+        "VERSION"
+      ],
+      "message": "chore(release): ${nextRelease.version}\n\n${nextRelease.notes}"
+    }],
     "@semantic-release/github"
-  ],
-  "branches": [
-    "main"
   ]
 }

CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Conventional Commits](https://www.conventionalcommits.org/) and is generated automatically by **semantic-release**.
+
+## [Unreleased]
+
+- Pending changes not yet released.

README.md

@@ -19,17 +19,17 @@ This action uses typescript and is built from the [typescript-action](https://gi
 
 This action can be called as part of your [GitHub action](https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions) workflows. to achieve this follow these steps:
 
-Add the following section to your existing workflow file:
+Add the following section to your existing workflow file (pin to a released major tag; the moving `v1` tag will always point at the latest backward-compatible release within the same major):
 
 ```yml
-      - name: Testing action to notify Teams
-        uses: nhs-england-tools/notify-msteams-action@v0.0.4
+      - name: Notify Teams
+        uses: nhs-england-tools/notify-msteams-action@v1
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           teams-webhook-url: ${{ secrets.TEAMS_WEBHOOK_URL }}
           message-title: "Replace with an appropriate title"
           message-text: "Replace with appropriate text"
-          link: https://google.com
+          link: https://example.org
 ```
 
 Follow the instructions [to add an Incoming Webhook](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook?tabs=dotnet) to the Teams channel of your choice.
@@ -76,6 +76,58 @@ An example of how the notification could appear in Microsoft Teams is provided:
 
 ![Microsoft Teams notification showing the adaptive card being displayed to the user for a "Pull request opened" event](docs/images/msteams-action-notification.png)
 
+### Versioning & Release Process
+
+This repository uses [semantic-release](https://semantic-release.gitbook.io/) to automatically:
+
+- Determine the next version from Conventional Commit messages.
+- Generate release notes and create a GitHub Release with tag `vX.Y.Z`.
+- Build and bundle the Action (TypeScript -> single `dist/index.js`).
+- Commit the generated `dist/` assets, the updated `package.json` (and `package-lock.json`) version metadata, and the `VERSION` file as part of the release commit.
+- Update the moving major tag (e.g. `v1`) to point to the latest release of that major.
+- Update the consolidated changelog in `CHANGELOG.md`.
+
+Consumers SHOULD depend on a major tag (e.g. `@v1`) or a fully qualified tag (e.g. `@v1.2.3`). The `main` branch is not guaranteed to contain built artefacts and must not be referenced directly in external workflows.
+
+For information about signed release commits, using a GitHub App for least-privilege release automation, key rotation, and revocation, see: [Release Signing & GitHub App](docs/developer-guides/Release_Signing_and_GitHub_App.md).
+
+### Developer Guides Index
+
+Centralised list of developer-facing guides in this repository:
+
+| Guide | Description |
+|-------|-------------|
+| [Bash and Make](docs/developer-guides/Bash_and_Make.md) | Conventions and patterns for Make targets and supporting Bash scripts, including target signatures and reuse. |
+| [Scripting Docker](docs/developer-guides/Scripting_Docker.md) | Opinionated Docker workflows: build, test, version (CalVer patterns), push and image management conventions. |
+| [Scripting Terraform](docs/developer-guides/Scripting_Terraform.md) | Terraform automation via Make wrappers, structure, state handling, quality enforcement and CI integration. |
+| [Release Process](docs/developer-guides/Release_Process.md) | End-to-end semantic-release driven publish pipeline and rationale for build-at-release strategy. |
+| [Release Signing & GitHub App](docs/developer-guides/Release_Signing_and_GitHub_App.md) | Secure release provenance: GitHub App token usage, GPG key generation, rotation and revocation procedures. |
+| [Sign Git commits](docs/user-guides/Sign_Git_commits.md) | How to configure and use GPG or SSH for commit signature verification locally and in CI. |
+
+### Contributing (Important Policy About `dist/`)
+
+Do not commit the `dist/` directory in pull requests. The CI pipeline will fail the PR if `dist/` is present. The release workflow rebuilds and commits `dist/` automatically. This keeps review noise low and ensures reproducible builds.
+
+To test local modifications, run:
+
+```bash
+npm ci
+npm run package
+```
+
+Then you can reference the action locally in a workflow within this repository using `uses: ./` (which will use the freshly generated `dist/`).
+
+### Conventional Commits
+
+To trigger proper version bumps, use the Conventional Commits format, for example:
+
+- `feat: add support for message colour`
+- `fix: correct Teams webhook error handling`
+- `chore: update dependencies`
+- `docs: clarify usage section`
+
+Breaking changes must include `!` after the type or the phrase `BREAKING CHANGE:` in the footer.
+
 ## Contacts
 
 Provide a way to contact the owners of this project. It can be a team, an individual or information on the means of getting in touch via active communication channels, e.g. opening a GitHub discussion, raising an issue, etc.

docs/developer-guides/Release_Process.md

@@ -0,0 +1,113 @@
+# Release Process
+
+This repository uses **semantic-release** to fully automate versioning and publishing of the GitHub Action.
+
+For details on securely signing release commits and using a GitHub App token, see the companion guide: [Release Signing & GitHub App](./Release_Signing_and_GitHub_App.md).
+
+## Overview
+
+1. Developers raise pull requests with source changes only (no `dist/` directory committed).
+2. The pull request workflow performs a semantic-release dry run to preview the next version.
+3. Once changes are merged to `main`, the publish workflow:
+
+   - Checks out the code.
+   - Installs dependencies and builds the production bundle with `npm run package` (emits `dist/index.js` + `licenses.txt`).
+   - Runs `semantic-release` which:
+   - Calculates the next version from Conventional Commits.
+   - Updates release notes and creates a Git tag `vX.Y.Z`.
+   - Commits the generated `dist/` assets, updated `package.json` / `package-lock.json` version metadata, and the `VERSION` file via the `@semantic-release/git` plugin.
+   - Creates a GitHub Release.
+   - Updates the moving major tag (e.g. `v1`) to the new version tag.
+   - (If repository secrets `GITHUB_APP_SIGNING_KEY`, `GITHUB_APP_SIGNING_KEY_ID`, and `GITHUB_APP_SIGNING_KEY_PASSPHRASE` are configured) imports the GPG key and signs the release commit and tag using a GitHub App.
+
+## Rationale
+
+Bundling only at release time avoids large, noisy diffs in pull requests and guarantees that the published artefact matches the exact commit that semantic-release tags.
+
+## Usage for Consumers
+
+Reference the Action via a tag, ideally the major tag:
+
+```yaml
+uses: nhs-england-tools/notify-msteams-action@v1
+```
+
+Pin to a specific minor/patch if you require full immutability:
+
+```yaml
+uses: nhs-england-tools/notify-msteams-action@v1.2.3
+```
+
+Avoid using `@main` externally, because the branch does not contain a guaranteed built `dist/` bundle.
+
+## Developer Workflow
+
+```bash
+# Install dependencies
+npm ci
+# Run tests & quality gates
+npm test
+npm run lint
+# Build bundle for local testing (not committed)
+npm run package
+```
+
+You can validate the action locally by creating a temporary workflow that uses `uses: ./`.
+
+## Conventional Commit Examples
+
+| Type  | Purpose                                | Example                                        |
+|-------|-----------------------------------------|------------------------------------------------|
+| `feat`  | New feature (minor bump)                | `feat: support custom message colour`          |
+| `fix`   | Bug fix (patch bump)                    | `fix: correct adaptive card JSON schema`       |
+| `chore` | Build/tooling changes                   | `chore: update eslint config`                  |
+| `docs`  | Documentation updates                   | `docs: add release process guide`              |
+| `perf`  | Performance improvement                 | `perf: reduce bundle size`                     |
+| `refactor` | Non-functional code change           | `refactor: simplify card builder`              |
+
+Breaking changes: add `!` (`feat!:`) or a `BREAKING CHANGE:` footer.
+
+## Failing Conditions
+
+The guard job fails a pull request if `dist/` is present. Remove it before requesting review.
+
+## Manual Intervention
+
+If a release must be re-run (rare):
+
+1. Revert the release commit if necessary.
+2. Amend commit messages to adjust semantic meaning.
+3. Push to `main` again and allow the publish workflow to execute.
+
+Avoid editing tags directly; let semantic-release manage them.
+
+## Future Improvements
+
+- Add changelog generation (`@semantic-release/changelog`) if a persistent `CHANGELOG.md` is desired.
+- Add an integration test workflow that consumes the just-published tag.
+
+---
+Maintainers: ensure `permissions: contents: write` is preserved in the publish workflow for tag/commit operations.
+
+### Commit Signing with GitHub App
+
+If branch protection requires signed commits, this repository uses GitHub App native commit signing:
+
+1. Create a GitHub App with commit signing enabled and generate both authentication and signing keys.
+2. Configure the following repository secrets:
+   - `GITHUB_APP_ID`: GitHub App ID for authentication
+   - `GITHUB_APP_PRIVATE_KEY`: App private key (PEM format) for token generation
+   - `GITHUB_APP_SIGNING_KEY_ID`: GPG key ID for commit signing
+   - `GITHUB_APP_SIGNING_KEY`: ASCII-armoured GPG private key content
+   - `GITHUB_APP_SIGNING_KEY_PASSPHRASE`: Passphrase for the GPG signing key
+
+On publish, the workflow:
+
+1. Generates a GitHub App installation token for authentication.
+2. Creates a GPG wrapper script that handles passphrase injection automatically.
+3. Imports the GPG signing key and configures git to use the wrapper script.
+4. Runs semantic-release which creates signed commits and tags attributed to the GitHub App.
+
+If the signing secrets are absent, semantic-release proceeds with unsigned commits (which will fail if branch protection mandates signatures—therefore the secrets must be present in that case).
+
+Complete setup procedures (key generation, GitHub App configuration, rotation, revocation) are documented in [Release Signing & GitHub App](./Release_Signing_and_GitHub_App.md).