From 64d6b81b42da54a79387abf19eb8ed145809f835 Mon Sep 17 00:00:00 2001
From: Kris Bloe <2674722+chrisbloe@users.noreply.github.com>
Date: Wed, 10 Sep 2025 15:05:56 +0100
Subject: [PATCH 01/21] Revise GPG signing guide for macOS & Windows

Updated instructions for GPG key generation and configuration on macOS and Windows. Also updated GitHub Actions checkout action version.
---
 practices/guides/commit-signing.md | 163 +++++++++++++++++++----------
 1 file changed, 108 insertions(+), 55 deletions(-)

diff --git a/practices/guides/commit-signing.md b/practices/guides/commit-signing.md
index 9021bab9..c9d6fa3f 100644
--- a/practices/guides/commit-signing.md
+++ b/practices/guides/commit-signing.md
@@ -13,76 +13,129 @@
 
 ### macOS
 
-- Install the [Brew package manager](https://brew.sh)
+1. Install `gnupg` & `pinentry-mac` with [Brew](https://brew.sh):
 
-```bash
-brew upgrade
-brew install gnupg pinentry-mac
-gpg --full-generate-key
-```
+    ```bash
+    brew upgrade
+    brew install gnupg pinentry-mac
+    sed -i '' '/^export GPG_TTY/d' ~/.zshrc
+    echo export GPG_TTY=\$\(tty\) >> ~/.zshrc
+    source ~/.zshrc
+    PINENTRY_BIN=$(whereis -q pinentry-mac)
+    touch ~/.gnupg/gpg-agent.conf
+    sed -i '' '/^pinentry-program/d' ~/.gnupg/gpg-agent.conf
+    echo "pinentry-program ${PINENTRY_BIN}" >> ~/.gnupg/gpg-agent.conf
+    gpgconf --kill gpg-agent
+    ```
 
-- Accept the defaults, Curve 25519 etc.
-- Enter your GitHub account name as the Real Name
-- Enter your GitHub account email as the Email Address
-- Avoid adding a comment (this *may* prevent git from auto-selecting a key - see Troubleshooting section below)
-- You can use the privacy *@users.noreply.github.com* email address listed in the GitHub profile: *Settings > Email*
-- Define a passphrase for the key and keep it in your password manager
+1. Create a new GPG key:
 
-```bash
-gpg --armor --export ${my_email_address} | pbcopy
-```
+    ```bash
+    gpg --full-generate-key
+    ```
 
-- Public key is now in your clipboard - in your GitHub account add it to your profile via *Settings > SSH and GPG Keys> Add New GPG Key*
-- Paste it in
+    1. Pick `RSA and RSA`, or `RSA (sign only)` (there is no elliptic curve cryptography (ECC) support at the time of writing)
+    1. `keysize` = `4096` bits (the minimum accepted for GitHub)
+    1. `Real name` = Your GitHub handle
+    1. `Email address` = Your GitHub account email [listed on your GitHub profile](https://github.com/settings/emails) (you can use the privacy *@users.noreply.github.com* email address): `Settings` -> `Emails` -> `Keep my email addresses private`)
 
-```bash
-git config --global user.email ${my_email_address} # same one used during key generation
-git config --global user.name ${my_username}
-git config --global commit.gpgsign true
-sed -i '' '/^export GPG_TTY/d' ~/.zshrc
-echo export GPG_TTY=\$\(tty\) >> ~/.zshrc
-source ~/.zshrc
-PINENTRY_BIN=$(whereis -q pinentry-mac)
-sed -i '' '/^pinentry-program/d' ~/.gnupg/gpg-agent.conf
-echo "pinentry-program ${PINENTRY_BIN}" >> ~/.gnupg/gpg-agent.conf
-gpgconf --kill gpg-agent
-```
+        > If you go for the private email option, consider enabling `Block command line pushes that expose my email`.
+    1. Avoid adding a comment (this *may* prevent git from auto-selecting a key - see Troubleshooting section below)
+    1. Define a passphrase for the key
+
+1. Check the key was made successfully:
+
+    ```bash
+    gpg -k
+    ```
 
-The first time you commit you will be prompted to add the GPG key passphrase to the macOS Keychain. Thereafter signing will happen seamlessly without prompts.
+1. Export the PGP PUBLIC KEY (to your clipboard):
 
-Most of the published solutions for this don't work because *brew* seems to have moved the default folder for binaries, plus many guides contain obsolete settings for *gpg-agent*.
+    ```bash
+    gpg --armor --export ${my_email_address} | pbcopy
+    ```
+
+1. [Add the public key to your GitHub account](https://github.com/settings/gpg/new) (`Settings` -> `SSH and GPG keys` -> `New GPG key`)
+
+    > Note the `Key ID` as you'll need this in the next step.
+
+1. Set your local git config to use GPG signing:
+
+    ```bash
+    git config --global user.email ${my_email_address} # same one used during key generation
+    git config --global user.name ${my_username}
+    git config --global user.signingkey = ${key_id}
+    git config --global commit.gpgsign true
+    git config --global tag.gpgsign true
+    ```
+
+> The first time you commit you will be prompted to add the GPG key passphrase to the macOS Keychain. Thereafter signing will happen seamlessly without prompts.
+>
+> Most of the published solutions for this don't work because *brew* seems to have moved the default folder for binaries, plus many guides contain obsolete settings for *gpg-agent*.
 
 ### Windows
 
-- Install [Git for Windows](https://git-scm.com/download/win), which includes Bash and GnuPG
-- Right-click on the Desktop > *Git Bash Here*
+1. Install [Git for Windows](https://git-scm.com/download/win) (which includes Bash and GnuPG)
+1. Right-click on the Desktop -> `Open Git Bash here`
+1. Create a new GPG key:
 
-```bash
-gpg --full-generate-key
-```
+    ```bash
+    gpg --full-generate-key
+    ```
 
-- Pick *RSA and RSA*, or *RSA (sign only)* - there is no elliptic curve cryptography (ECC) support at the time of writing
-- Set key size to 4096 bit, the minimum accepted for GitHub
-- Enter your GitHub account name as the Real Name
-- Enter your GitHub account email as the Email Address
-- Avoid adding a comment (this *may* prevent git from auto-selecting a key - see Troubleshooting section below)
-- You can use the privacy *@users.noreply.github.com* email address listed in the GitHub profile: *Settings > Email*
-- Define a passphrase for the key and keep it in your password manager
+    1. Pick `RSA and RSA`, or `RSA (sign only)` (there is no elliptic curve cryptography (ECC) support at the time of writing)
+    1. `keysize` = `4096` bits (the minimum accepted for GitHub)
+    1. `Real name` = Your GitHub handle
+    1. `Email address` = Your GitHub account email [listed on your GitHub profile](https://github.com/settings/emails) (you can use the privacy *@users.noreply.github.com* email address): `Settings` -> `Emails` -> `Keep my email addresses private`)
 
-```bash
-gpg --armor --export ${my_email_address} | clip
-```
+        > If you go for the private email option, consider enabling `Block command line pushes that expose my email`.
+    1. Avoid adding a comment (this *may* prevent git from auto-selecting a key - see Troubleshooting section below)
+    1. Define a passphrase for the key
 
-- Public key is now in your clipboard - in your GitHub account add it to your profile via *Settings > SSH and GPG Keys> Add New GPG Key*
-- Paste it in
+1. Export the PGP PUBLIC KEY (to your clipboard):
 
-```bash
-git config --global user.email ${my_email_address} # same one used during key generation
-git config --global user.name ${my_username}
-git config --global commit.gpgsign true
-```
+    ```bash
+    gpg --armor --export ${my_email_address} | clip
+    ```
+
+1. [Add the public key to your GitHub account](https://github.com/settings/gpg/new) (`Settings` -> `SSH and GPG keys` -> `New GPG key`)
+
+    > Note the `Key ID` as you'll need this in the next step.
+
+1. Set your local git config to use GPG signing:
+
+    ```bash
+    git config --global user.email ${my_email_address} # same one used during key generation
+    git config --global user.name ${my_username}
+    git config --global user.signingkey = ${key_id}
+    git config --global commit.gpgsign true
+    git config --global tag.gpgsign true
+    ```
+
+1. Optional: Your new GPG key can be used within WSL, but not from Windows; to enable this:
+
+    1. Export the key:
+
+        ```bash
+        gpg --output <GitHub handle>.pgp --export-secret-key ${my_email_address}$
+        ```
+
+    1. Install [Gpg4win](https://www.gpg4win.org/) (which includes GnuPG and Kleopatra)
+
+        > **Ensure both `GnuPG` and `Kleopatra` are installed!**
+
+    1. Open Kleopatra -> `Import` -> Select the `<GitHub handle>.pgp` file created in the first step.
+    1. In `cmd`, set your local git config to use GPG signing:
+
+        ```bash
+        git config --global user.email ${my_email_address} # same one used during key generation
+        git config --global user.name ${my_username}
+        git config --global user.signingkey = ${key_id}
+        git config --global commit.gpgsign true
+        git config --global tag.gpgsign true
+        ```
 
-When you commit you will be prompted to enter the GPG key passphrase into a Pinentry window.
+> When you commit, you'll now be prompted to enter the GPG key passphrase into a Pinentry window.
 
 ## From Pipelines
 
@@ -97,7 +150,7 @@ The workflow would then use a Personal Access Token, stored with the GPG private
 ```yaml
 steps:
   - name: Checkout
-    uses: actions/checkout@v3
+    uses: actions/checkout@v5
     with:
       token: ${{ secrets.BOT_PAT }}
       ref: main

From 9ac0b03ca7220556c415d62d60aa96aefaaddf33 Mon Sep 17 00:00:00 2001
From: Kris Bloe <2674722+chrisbloe@users.noreply.github.com>
Date: Thu, 11 Sep 2025 15:40:07 +0100
Subject: [PATCH 02/21] Additional tweaks

---
 practices/guides/commit-signing.md | 36 ++++++++++++++++++++++--------
 1 file changed, 27 insertions(+), 9 deletions(-)

diff --git a/practices/guides/commit-signing.md b/practices/guides/commit-signing.md
index c9d6fa3f..de823f4c 100644
--- a/practices/guides/commit-signing.md
+++ b/practices/guides/commit-signing.md
@@ -36,22 +36,19 @@
 
     1. Pick `RSA and RSA`, or `RSA (sign only)` (there is no elliptic curve cryptography (ECC) support at the time of writing)
     1. `keysize` = `4096` bits (the minimum accepted for GitHub)
+    1. Select a key expiry time (personal choice)
     1. `Real name` = Your GitHub handle
     1. `Email address` = Your GitHub account email [listed on your GitHub profile](https://github.com/settings/emails) (you can use the privacy *@users.noreply.github.com* email address): `Settings` -> `Emails` -> `Keep my email addresses private`)
 
         > If you go for the private email option, consider enabling `Block command line pushes that expose my email`.
+
     1. Avoid adding a comment (this *may* prevent git from auto-selecting a key - see Troubleshooting section below)
     1. Define a passphrase for the key
 
-1. Check the key was made successfully:
-
-    ```bash
-    gpg -k
-    ```
-
 1. Export the PGP PUBLIC KEY (to your clipboard):
 
     ```bash
+    gpg -k # This should list the new key
     gpg --armor --export ${my_email_address} | pbcopy
     ```
 
@@ -76,7 +73,7 @@
 ### Windows
 
 1. Install [Git for Windows](https://git-scm.com/download/win) (which includes Bash and GnuPG)
-1. Right-click on the Desktop -> `Open Git Bash here`
+1. Open `Git Bash`
 1. Create a new GPG key:
 
     ```bash
@@ -85,16 +82,19 @@
 
     1. Pick `RSA and RSA`, or `RSA (sign only)` (there is no elliptic curve cryptography (ECC) support at the time of writing)
     1. `keysize` = `4096` bits (the minimum accepted for GitHub)
+    1. Select a key expiry time (personal choice)
     1. `Real name` = Your GitHub handle
     1. `Email address` = Your GitHub account email [listed on your GitHub profile](https://github.com/settings/emails) (you can use the privacy *@users.noreply.github.com* email address): `Settings` -> `Emails` -> `Keep my email addresses private`)
 
         > If you go for the private email option, consider enabling `Block command line pushes that expose my email`.
+
     1. Avoid adding a comment (this *may* prevent git from auto-selecting a key - see Troubleshooting section below)
     1. Define a passphrase for the key
 
 1. Export the PGP PUBLIC KEY (to your clipboard):
 
     ```bash
+    gpg -k # This should list the new key
     gpg --armor --export ${my_email_address} | clip
     ```
 
@@ -112,7 +112,7 @@
     git config --global tag.gpgsign true
     ```
 
-1. Optional: Your new GPG key can be used within WSL, but not from Windows; to enable this:
+1. Now your key is created, make it avalable within Windows:
 
     1. Export the key:
 
@@ -124,10 +124,11 @@
 
         > **Ensure both `GnuPG` and `Kleopatra` are installed!**
 
-    1. Open Kleopatra -> `Import` -> Select the `<GitHub handle>.pgp` file created in the first step.
+    1. Open Kleopatra -> `Import` -> Select the `<GitHub handle>.pgp` file created in the first step
     1. In `cmd`, set your local git config to use GPG signing:
 
         ```bash
+        gpg -k # This should list the new key
         git config --global user.email ${my_email_address} # same one used during key generation
         git config --global user.name ${my_username}
         git config --global user.signingkey = ${key_id}
@@ -135,6 +136,23 @@
         git config --global tag.gpgsign true
         ```
 
+1. And finally, make it avalable within WSL:
+
+    1. Within Ubuntu:
+
+        ```bash
+        sudo ln -s /mnt/c/Program\ Files\ \(x86\)/GnuPG/bin/gpg.exe /usr/local/bin/gpg
+        sudo ln -s gpg /usr/local/bin/gpg2
+        ```
+
+    1. Close and reopen your Ubuntu terminal
+
+    1. Test the key is visible:
+
+        ```bash
+        gpg -k # This should list the new key
+        ```
+
 > When you commit, you'll now be prompted to enter the GPG key passphrase into a Pinentry window.
 
 ## From Pipelines

From d122fe8527897223036f862481b0cf877832ee1b Mon Sep 17 00:00:00 2001
From: Kris Bloe <2674722+chrisbloe@users.noreply.github.com>
Date: Thu, 11 Sep 2025 16:13:01 +0100
Subject: [PATCH 03/21] Removed erroneous = character

---
 practices/guides/commit-signing.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/practices/guides/commit-signing.md b/practices/guides/commit-signing.md
index de823f4c..906d1ab4 100644
--- a/practices/guides/commit-signing.md
+++ b/practices/guides/commit-signing.md
@@ -35,10 +35,10 @@
     ```
 
     1. Pick `RSA and RSA`, or `RSA (sign only)` (there is no elliptic curve cryptography (ECC) support at the time of writing)
-    1. `keysize` = `4096` bits (the minimum accepted for GitHub)
+    1. `keysize` `4096` bits (the minimum accepted for GitHub)
     1. Select a key expiry time (personal choice)
-    1. `Real name` = Your GitHub handle
-    1. `Email address` = Your GitHub account email [listed on your GitHub profile](https://github.com/settings/emails) (you can use the privacy *@users.noreply.github.com* email address): `Settings` -> `Emails` -> `Keep my email addresses private`)
+    1. `Real name` Your GitHub handle
+    1. `Email address` Your GitHub account email [listed on your GitHub profile](https://github.com/settings/emails) (you can use the privacy *@users.noreply.github.com* email address): `Settings` -> `Emails` -> `Keep my email addresses private`)
 
         > If you go for the private email option, consider enabling `Block command line pushes that expose my email`.
 
@@ -61,7 +61,7 @@
     ```bash
     git config --global user.email ${my_email_address} # same one used during key generation
     git config --global user.name ${my_username}
-    git config --global user.signingkey = ${key_id}
+    git config --global user.signingkey ${key_id}
     git config --global commit.gpgsign true
     git config --global tag.gpgsign true
     ```
@@ -107,7 +107,7 @@
     ```bash
     git config --global user.email ${my_email_address} # same one used during key generation
     git config --global user.name ${my_username}
-    git config --global user.signingkey = ${key_id}
+    git config --global user.signingkey ${key_id}
     git config --global commit.gpgsign true
     git config --global tag.gpgsign true
     ```
@@ -131,7 +131,7 @@
         gpg -k # This should list the new key
         git config --global user.email ${my_email_address} # same one used during key generation
         git config --global user.name ${my_username}
-        git config --global user.signingkey = ${key_id}
+        git config --global user.signingkey ${key_id}
         git config --global commit.gpgsign true
         git config --global tag.gpgsign true
         ```

From 71b7899dac44d17314b9b1febc0de4e0879a62f6 Mon Sep 17 00:00:00 2001
From: Kris Bloe <2674722+chrisbloe@users.noreply.github.com>
Date: Thu, 11 Sep 2025 16:21:53 +0100
Subject: [PATCH 04/21] Additional steps

---
 practices/guides/commit-signing.md | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/practices/guides/commit-signing.md b/practices/guides/commit-signing.md
index 906d1ab4..1b2360b8 100644
--- a/practices/guides/commit-signing.md
+++ b/practices/guides/commit-signing.md
@@ -45,7 +45,7 @@
     1. Avoid adding a comment (this *may* prevent git from auto-selecting a key - see Troubleshooting section below)
     1. Define a passphrase for the key
 
-1. Export the PGP PUBLIC KEY (to your clipboard):
+1. Test the key is visible and export the PGP PUBLIC KEY (to your clipboard):
 
     ```bash
     gpg -k # This should list the new key
@@ -91,7 +91,7 @@
     1. Avoid adding a comment (this *may* prevent git from auto-selecting a key - see Troubleshooting section below)
     1. Define a passphrase for the key
 
-1. Export the PGP PUBLIC KEY (to your clipboard):
+1. Test the key is visible and export the PGP PUBLIC KEY (to your clipboard):
 
     ```bash
     gpg -k # This should list the new key
@@ -125,7 +125,7 @@
         > **Ensure both `GnuPG` and `Kleopatra` are installed!**
 
     1. Open Kleopatra -> `Import` -> Select the `<GitHub handle>.pgp` file created in the first step
-    1. In `cmd`, set your local git config to use GPG signing:
+    1. In `cmd`, test the key is visible and set your local git config to use GPG signing:
 
         ```bash
         gpg -k # This should list the new key
@@ -147,10 +147,15 @@
 
     1. Close and reopen your Ubuntu terminal
 
-    1. Test the key is visible:
+    1. Test the key is visible and set your local git config to use GPG signing:
 
         ```bash
         gpg -k # This should list the new key
+        git config --global user.email ${my_email_address} # same one used during key generation
+        git config --global user.name ${my_username}
+        git config --global user.signingkey ${key_id}
+        git config --global commit.gpgsign true
+        git config --global tag.gpgsign true
         ```
 
 > When you commit, you'll now be prompted to enter the GPG key passphrase into a Pinentry window.

From ab0d3b69f4863a6aa7e32ec83bad469082e39480 Mon Sep 17 00:00:00 2001
From: Kris Bloe <2674722+chrisbloe@users.noreply.github.com>
Date: Thu, 11 Sep 2025 16:25:03 +0100
Subject: [PATCH 05/21] Change username to github_handle in commit signing
 guide

---
 practices/guides/commit-signing.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/practices/guides/commit-signing.md b/practices/guides/commit-signing.md
index 1b2360b8..87d562a3 100644
--- a/practices/guides/commit-signing.md
+++ b/practices/guides/commit-signing.md
@@ -60,7 +60,7 @@
 
     ```bash
     git config --global user.email ${my_email_address} # same one used during key generation
-    git config --global user.name ${my_username}
+    git config --global user.name ${github_handle}
     git config --global user.signingkey ${key_id}
     git config --global commit.gpgsign true
     git config --global tag.gpgsign true
@@ -106,7 +106,7 @@
 
     ```bash
     git config --global user.email ${my_email_address} # same one used during key generation
-    git config --global user.name ${my_username}
+    git config --global user.name ${github_handle}
     git config --global user.signingkey ${key_id}
     git config --global commit.gpgsign true
     git config --global tag.gpgsign true
@@ -130,7 +130,7 @@
         ```bash
         gpg -k # This should list the new key
         git config --global user.email ${my_email_address} # same one used during key generation
-        git config --global user.name ${my_username}
+        git config --global user.name ${github_handle}
         git config --global user.signingkey ${key_id}
         git config --global commit.gpgsign true
         git config --global tag.gpgsign true
@@ -152,7 +152,7 @@
         ```bash
         gpg -k # This should list the new key
         git config --global user.email ${my_email_address} # same one used during key generation
-        git config --global user.name ${my_username}
+        git config --global user.name ${github_handle}
         git config --global user.signingkey ${key_id}
         git config --global commit.gpgsign true
         git config --global tag.gpgsign true

From 95e4aa2736b7ffc1a9eb7686c524fb30531e6a0c Mon Sep 17 00:00:00 2001
From: Kris Bloe <2674722+chrisbloe@users.noreply.github.com>
Date: Tue, 16 Sep 2025 16:29:24 +0100
Subject: [PATCH 06/21] Clarify email and handle placeholders in commit signing
 guide

Updated email and handle placeholders in GPG signing instructions for clarity.
---
 practices/guides/commit-signing.md | 44 ++++++++++++++++++------------
 1 file changed, 26 insertions(+), 18 deletions(-)

diff --git a/practices/guides/commit-signing.md b/practices/guides/commit-signing.md
index 87d562a3..7d1aaef9 100644
--- a/practices/guides/commit-signing.md
+++ b/practices/guides/commit-signing.md
@@ -43,15 +43,19 @@
         > If you go for the private email option, consider enabling `Block command line pushes that expose my email`.
 
     1. Avoid adding a comment (this *may* prevent git from auto-selecting a key - see Troubleshooting section below)
+    1. Review your inputs and press enter `O` to confirm
     1. Define a passphrase for the key
 
 1. Test the key is visible and export the PGP PUBLIC KEY (to your clipboard):
 
     ```bash
     gpg -k # This should list the new key
-    gpg --armor --export ${my_email_address} | pbcopy
+    gpg --armor --export <my_email_address> | pbcopy
     ```
 
+    > [!NOTE]
+    > Your PGP PUBLIC KEY is now in your clipboard!
+
 1. [Add the public key to your GitHub account](https://github.com/settings/gpg/new) (`Settings` -> `SSH and GPG keys` -> `New GPG key`)
 
     > Note the `Key ID` as you'll need this in the next step.
@@ -59,9 +63,9 @@
 1. Set your local git config to use GPG signing:
 
     ```bash
-    git config --global user.email ${my_email_address} # same one used during key generation
-    git config --global user.name ${github_handle}
-    git config --global user.signingkey ${key_id}
+    git config --global user.email <my_email_address> # same one used during key generation
+    git config --global user.name <github_handle>
+    git config --global user.signingkey <key_id>
     git config --global commit.gpgsign true
     git config --global tag.gpgsign true
     ```
@@ -72,7 +76,7 @@
 
 ### Windows
 
-1. Install [Git for Windows](https://git-scm.com/download/win) (which includes Bash and GnuPG)
+1. Install (as administrator) [Git for Windows](https://git-scm.com/download/win) (which includes Bash and GnuPG)
 1. Open `Git Bash`
 1. Create a new GPG key:
 
@@ -89,15 +93,19 @@
         > If you go for the private email option, consider enabling `Block command line pushes that expose my email`.
 
     1. Avoid adding a comment (this *may* prevent git from auto-selecting a key - see Troubleshooting section below)
-    1. Define a passphrase for the key
+    1. Review your inputs and press enter `O` to confirm
+    1. A new window called pinentry will appear prompting you to enter a passphrase.
 
 1. Test the key is visible and export the PGP PUBLIC KEY (to your clipboard):
 
     ```bash
     gpg -k # This should list the new key
-    gpg --armor --export ${my_email_address} | clip
+    gpg --armor --export <my_email_address> | clip
     ```
 
+    > [!NOTE]
+    > Your PGP PUBLIC KEY is now in your clipboard!
+
 1. [Add the public key to your GitHub account](https://github.com/settings/gpg/new) (`Settings` -> `SSH and GPG keys` -> `New GPG key`)
 
     > Note the `Key ID` as you'll need this in the next step.
@@ -105,9 +113,9 @@
 1. Set your local git config to use GPG signing:
 
     ```bash
-    git config --global user.email ${my_email_address} # same one used during key generation
-    git config --global user.name ${github_handle}
-    git config --global user.signingkey ${key_id}
+    git config --global user.email <my_email_address> # same one used during key generation
+    git config --global user.name <github_handle>
+    git config --global user.signingkey <key_id>
     git config --global commit.gpgsign true
     git config --global tag.gpgsign true
     ```
@@ -117,10 +125,10 @@
     1. Export the key:
 
         ```bash
-        gpg --output <GitHub handle>.pgp --export-secret-key ${my_email_address}$
+        gpg --output <GitHub handle>.pgp --export-secret-key <my_email_address>
         ```
 
-    1. Install [Gpg4win](https://www.gpg4win.org/) (which includes GnuPG and Kleopatra)
+    1. Install (as administrator) [Gpg4win](https://www.gpg4win.org/) (which includes GnuPG and Kleopatra)
 
         > **Ensure both `GnuPG` and `Kleopatra` are installed!**
 
@@ -129,9 +137,9 @@
 
         ```bash
         gpg -k # This should list the new key
-        git config --global user.email ${my_email_address} # same one used during key generation
-        git config --global user.name ${github_handle}
-        git config --global user.signingkey ${key_id}
+        git config --global user.email <my_email_address> # same one used during key generation
+        git config --global user.name <github_handle>
+        git config --global user.signingkey <key_id>
         git config --global commit.gpgsign true
         git config --global tag.gpgsign true
         ```
@@ -151,9 +159,9 @@
 
         ```bash
         gpg -k # This should list the new key
-        git config --global user.email ${my_email_address} # same one used during key generation
-        git config --global user.name ${github_handle}
-        git config --global user.signingkey ${key_id}
+        git config --global user.email <my_email_address> # same one used during key generation
+        git config --global user.name <github_handle>
+        git config --global user.signingkey <key_id>
         git config --global commit.gpgsign true
         git config --global tag.gpgsign true
         ```

From 551e4e3442ca3fc7673f51533a5c4b31babd2cf4 Mon Sep 17 00:00:00 2001
From: Kris Bloe <2674722+chrisbloe@users.noreply.github.com>
Date: Tue, 16 Sep 2025 16:35:53 +0100
Subject: [PATCH 07/21] Changing the NOTE placement

---
 practices/guides/commit-signing.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/practices/guides/commit-signing.md b/practices/guides/commit-signing.md
index 7d1aaef9..6e1c9469 100644
--- a/practices/guides/commit-signing.md
+++ b/practices/guides/commit-signing.md
@@ -53,8 +53,8 @@
     gpg --armor --export <my_email_address> | pbcopy
     ```
 
-    > [!NOTE]
-    > Your PGP PUBLIC KEY is now in your clipboard!
+> [!NOTE]
+> Your PGP PUBLIC KEY is now in your clipboard!
 
 1. [Add the public key to your GitHub account](https://github.com/settings/gpg/new) (`Settings` -> `SSH and GPG keys` -> `New GPG key`)
 
@@ -103,8 +103,8 @@
     gpg --armor --export <my_email_address> | clip
     ```
 
-    > [!NOTE]
-    > Your PGP PUBLIC KEY is now in your clipboard!
+> [!NOTE]
+> Your PGP PUBLIC KEY is now in your clipboard!
 
 1. [Add the public key to your GitHub account](https://github.com/settings/gpg/new) (`Settings` -> `SSH and GPG keys` -> `New GPG key`)
 

From bffd81bc73e4d830deaf27c5f4180d6bad61c3f4 Mon Sep 17 00:00:00 2001
From: Kris Bloe <2674722+chrisbloe@users.noreply.github.com>
Date: Tue, 16 Sep 2025 16:37:14 +0100
Subject: [PATCH 08/21] Redoing a NOTE

Updated note formatting for clipboard instructions.
---
 practices/guides/commit-signing.md | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/practices/guides/commit-signing.md b/practices/guides/commit-signing.md
index 6e1c9469..fd486f3c 100644
--- a/practices/guides/commit-signing.md
+++ b/practices/guides/commit-signing.md
@@ -53,8 +53,7 @@
     gpg --armor --export <my_email_address> | pbcopy
     ```
 
-> [!NOTE]
-> Your PGP PUBLIC KEY is now in your clipboard!
+        > Your PGP PUBLIC KEY is now in your clipboard!
 
 1. [Add the public key to your GitHub account](https://github.com/settings/gpg/new) (`Settings` -> `SSH and GPG keys` -> `New GPG key`)
 
@@ -103,8 +102,8 @@
     gpg --armor --export <my_email_address> | clip
     ```
 
-> [!NOTE]
-> Your PGP PUBLIC KEY is now in your clipboard!
+        > [!NOTE]
+        > Your PGP PUBLIC KEY is now in your clipboard!
 
 1. [Add the public key to your GitHub account](https://github.com/settings/gpg/new) (`Settings` -> `SSH and GPG keys` -> `New GPG key`)
 

From fe12d503880f42db8f2c7f37d88b8e10a418013f Mon Sep 17 00:00:00 2001
From: Kris Bloe <2674722+chrisbloe@users.noreply.github.com>
Date: Tue, 16 Sep 2025 16:38:16 +0100
Subject: [PATCH 09/21] NOTE changes

---
 practices/guides/commit-signing.md | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/practices/guides/commit-signing.md b/practices/guides/commit-signing.md
index fd486f3c..78d12574 100644
--- a/practices/guides/commit-signing.md
+++ b/practices/guides/commit-signing.md
@@ -53,7 +53,7 @@
     gpg --armor --export <my_email_address> | pbcopy
     ```
 
-        > Your PGP PUBLIC KEY is now in your clipboard!
+    > Your PGP PUBLIC KEY is now in your clipboard!
 
 1. [Add the public key to your GitHub account](https://github.com/settings/gpg/new) (`Settings` -> `SSH and GPG keys` -> `New GPG key`)
 
@@ -102,8 +102,7 @@
     gpg --armor --export <my_email_address> | clip
     ```
 
-        > [!NOTE]
-        > Your PGP PUBLIC KEY is now in your clipboard!
+    > Your PGP PUBLIC KEY is now in your clipboard!
 
 1. [Add the public key to your GitHub account](https://github.com/settings/gpg/new) (`Settings` -> `SSH and GPG keys` -> `New GPG key`)
 

From 6851f8721ee90ecc104650670448688d33ceaa39 Mon Sep 17 00:00:00 2001
From: Kris Bloe <2674722+chrisbloe@users.noreply.github.com>
Date: Thu, 18 Sep 2025 11:34:17 +0100
Subject: [PATCH 10/21] Create ~/.gnupg directory if it does not exist

---
 practices/guides/commit-signing.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/practices/guides/commit-signing.md b/practices/guides/commit-signing.md
index 78d12574..0d3d7757 100644
--- a/practices/guides/commit-signing.md
+++ b/practices/guides/commit-signing.md
@@ -22,6 +22,7 @@
     echo export GPG_TTY=\$\(tty\) >> ~/.zshrc
     source ~/.zshrc
     PINENTRY_BIN=$(whereis -q pinentry-mac)
+    mkdir -p ~/.gnupg
     touch ~/.gnupg/gpg-agent.conf
     sed -i '' '/^pinentry-program/d' ~/.gnupg/gpg-agent.conf
     echo "pinentry-program ${PINENTRY_BIN}" >> ~/.gnupg/gpg-agent.conf

From 39bd085f822f07176c458a8f4ff73e2db5c9286d Mon Sep 17 00:00:00 2001
From: Kris Bloe <2674722+chrisbloe@users.noreply.github.com>
Date: Thu, 18 Sep 2025 11:41:36 +0100
Subject: [PATCH 11/21] Revise Windows section to include WSL

Updated Windows section to include WSL in commit signing guide.
---
 practices/guides/commit-signing.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/practices/guides/commit-signing.md b/practices/guides/commit-signing.md
index 0d3d7757..b44602c9 100644
--- a/practices/guides/commit-signing.md
+++ b/practices/guides/commit-signing.md
@@ -74,7 +74,7 @@
 >
 > Most of the published solutions for this don't work because *brew* seems to have moved the default folder for binaries, plus many guides contain obsolete settings for *gpg-agent*.
 
-### Windows
+### Windows (includes WSL)
 
 1. Install (as administrator) [Git for Windows](https://git-scm.com/download/win) (which includes Bash and GnuPG)
 1. Open `Git Bash`

From d3bb721e0d646502cd6babdf2d19c94a49929496 Mon Sep 17 00:00:00 2001
From: Kris Bloe <2674722+chrisbloe@users.noreply.github.com>
Date: Thu, 18 Sep 2025 11:59:09 +0100
Subject: [PATCH 12/21] Change heading to 'Windows/WSL' for clarity

Updated the heading for Windows instructions to include WSL.
---
 practices/guides/commit-signing.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/practices/guides/commit-signing.md b/practices/guides/commit-signing.md
index b44602c9..273efcff 100644
--- a/practices/guides/commit-signing.md
+++ b/practices/guides/commit-signing.md
@@ -74,7 +74,7 @@
 >
 > Most of the published solutions for this don't work because *brew* seems to have moved the default folder for binaries, plus many guides contain obsolete settings for *gpg-agent*.
 
-### Windows (includes WSL)
+### Windows/WSL
 
 1. Install (as administrator) [Git for Windows](https://git-scm.com/download/win) (which includes Bash and GnuPG)
 1. Open `Git Bash`

From 88aed16b71cd52198d32620b8a671490e4cfb480 Mon Sep 17 00:00:00 2001
From: Kris Bloe <2674722+chrisbloe@users.noreply.github.com>
Date: Thu, 18 Sep 2025 12:00:00 +0100
Subject: [PATCH 13/21] Remove table of contents from commit signing guide as
 it's available in the UI

Removed table of contents from the commit signing guide.
---
 practices/guides/commit-signing.md | 9 ---------
 1 file changed, 9 deletions(-)

diff --git a/practices/guides/commit-signing.md b/practices/guides/commit-signing.md
index 273efcff..c4df8ae5 100644
--- a/practices/guides/commit-signing.md
+++ b/practices/guides/commit-signing.md
@@ -1,14 +1,5 @@
 # Git commit signing setup guide
 
-- [Git commit signing setup guide](#git-commit-signing-setup-guide)
-  - [From Workstations](#from-workstations)
-    - [macOS](#macos)
-    - [Windows](#windows)
-  - [From Pipelines](#from-pipelines)
-    - [GitHub Actions](#github-actions)
-    - [AWS CodePipeline](#aws-codepipeline)
-  - [Troubleshooting](#troubleshooting)
-
 ## From Workstations
 
 ### macOS

From c073060ba7bf60d7b2078d0fc1160ae3244bd5cf Mon Sep 17 00:00:00 2001
From: Kris Bloe <2674722+chrisbloe@users.noreply.github.com>
Date: Thu, 18 Sep 2025 12:18:52 +0100
Subject: [PATCH 14/21] Improve commit signing guide with clearer steps

---
 practices/guides/commit-signing.md | 36 +++++++++++++++++++++++++-----
 1 file changed, 30 insertions(+), 6 deletions(-)

diff --git a/practices/guides/commit-signing.md b/practices/guides/commit-signing.md
index c4df8ae5..da443811 100644
--- a/practices/guides/commit-signing.md
+++ b/practices/guides/commit-signing.md
@@ -61,9 +61,20 @@
     git config --global tag.gpgsign true
     ```
 
-> The first time you commit you will be prompted to add the GPG key passphrase to the macOS Keychain. Thereafter signing will happen seamlessly without prompts.
->
-> Most of the published solutions for this don't work because *brew* seems to have moved the default folder for binaries, plus many guides contain obsolete settings for *gpg-agent*.
+1. Test it works:
+
+    1. Create a temporary branch of your favourite repository.
+    1. Make an inconsequential whitesace change.
+    1. Commit the change.
+        1. You will be prompted for your GPG key passphrase - optionally select to add it to the macOS Keychain.
+    1. Check the latest commit shows a successful signing:
+
+        ```bash
+        $ git log --show-signature -1
+        ...
+        gpg: Good signature from "<github_handle> <<my_email_address>>" [ultimate]
+        ...
+        ```
 
 ### Windows/WSL
 
@@ -134,7 +145,7 @@
         git config --global tag.gpgsign true
         ```
 
-1. And finally, make it avalable within WSL:
+1. Now make it avalable within WSL:
 
     1. Within Ubuntu:
 
@@ -156,7 +167,20 @@
         git config --global tag.gpgsign true
         ```
 
-> When you commit, you'll now be prompted to enter the GPG key passphrase into a Pinentry window.
+1. Test it works:
+
+    1. Create a temporary branch of your favourite repository.
+    1. Make an inconsequential whitesace change.
+    1. Commit the change.
+        1. You will be prompted for your GPG key passphrase.
+    1. Check the latest commit shows a successful signing:
+
+        ```bash
+        $ git log --show-signature -1
+        ...
+        gpg: Good signature from "<github_handle> <<my_email_address>>" [ultimate]
+        ...
+        ```
 
 ## From Pipelines
 
@@ -212,7 +236,7 @@ if [[ ${BOT_SSH_KEY} != "None" ]]; then
   echo "StrictHostKeyChecking yes" >> ~/.ssh/config
   echo "UserKnownHostsFile=~/.ssh/known_hosts" >> ~/.ssh/config
   echo "${BOT_SSH_KEY}" > ~/.ssh/ssh_key
-  echo -e "\n\n" >>  ~/.ssh/ssh_key
+  echo -e "\n\n" >> ~/.ssh/ssh_key
   chmod 600 ~/.ssh/ssh_key
   eval "$(ssh-agent -s)"
   ssh-add ~/.ssh/ssh_key

From 504743fd80782044b5326b64997c8fa92c7cd495 Mon Sep 17 00:00:00 2001
From: Kris Bloe <2674722+chrisbloe@users.noreply.github.com>
Date: Tue, 23 Sep 2025 14:29:26 +0100
Subject: [PATCH 15/21] Fix typos in commit-signing.md

Corrected typos in the commit-signing guide regarding whitespace and availability instructions.
---
 practices/guides/commit-signing.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/practices/guides/commit-signing.md b/practices/guides/commit-signing.md
index da443811..206ac245 100644
--- a/practices/guides/commit-signing.md
+++ b/practices/guides/commit-signing.md
@@ -64,7 +64,7 @@
 1. Test it works:
 
     1. Create a temporary branch of your favourite repository.
-    1. Make an inconsequential whitesace change.
+    1. Make an inconsequential whitespace change.
     1. Commit the change.
         1. You will be prompted for your GPG key passphrase - optionally select to add it to the macOS Keychain.
     1. Check the latest commit shows a successful signing:
@@ -121,7 +121,7 @@
     git config --global tag.gpgsign true
     ```
 
-1. Now your key is created, make it avalable within Windows:
+1. Now your key is created, make it available within Windows:
 
     1. Export the key:
 
@@ -145,7 +145,7 @@
         git config --global tag.gpgsign true
         ```
 
-1. Now make it avalable within WSL:
+1. Now make it available within WSL:
 
     1. Within Ubuntu:
 
@@ -170,7 +170,7 @@
 1. Test it works:
 
     1. Create a temporary branch of your favourite repository.
-    1. Make an inconsequential whitesace change.
+    1. Make an inconsequential whitespace change.
     1. Commit the change.
         1. You will be prompted for your GPG key passphrase.
     1. Check the latest commit shows a successful signing:

From d0c38e0216861ae23cf62100d92ef559f533bf96 Mon Sep 17 00:00:00 2001
From: Kris Bloe <2674722+chrisbloe@users.noreply.github.com>
Date: Fri, 26 Sep 2025 11:00:02 +0100
Subject: [PATCH 16/21] Enhance commit signing guide with SSH instructions

Expanded the commit signing guide to include SSH signing instructions and troubleshooting tips.
---
 practices/guides/commit-signing.md | 72 +++++++++++++++++++++++++-----
 1 file changed, 62 insertions(+), 10 deletions(-)

diff --git a/practices/guides/commit-signing.md b/practices/guides/commit-signing.md
index 206ac245..f301efa4 100644
--- a/practices/guides/commit-signing.md
+++ b/practices/guides/commit-signing.md
@@ -1,8 +1,20 @@
 # Git commit signing setup guide
 
-## From Workstations
+Using GPG, SSH, or S/MIME, you can sign commits and tags locally. These commits and tags are marked as verified on GitHub so other people can be confident that the changes come from a trusted source.
 
-### macOS
+The instructions on this page focus on GPG and SSH.
+
+> You should only set up **one** of these options - **don't attempt to set up GPG and SSH commit signing**!
+
+See the full GitHub documentation [here](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification).
+
+## GPG commit signing
+
+### From Workstations
+
+If you have already committed and need to retrospectively sign commits, follow the instructions below, then follow the [retrospective commit signing instructions](./retrospective-commit-signing.md).
+
+#### macOS
 
 1. Install `gnupg` & `pinentry-mac` with [Brew](https://brew.sh):
 
@@ -76,7 +88,7 @@
         ...
         ```
 
-### Windows/WSL
+#### Windows/WSL
 
 1. Install (as administrator) [Git for Windows](https://git-scm.com/download/win) (which includes Bash and GnuPG)
 1. Open `Git Bash`
@@ -182,9 +194,9 @@
         ...
         ```
 
-## From Pipelines
+### From Pipelines
 
-### GitHub Actions
+#### GitHub Actions
 
 A GitHub Actions workflow will by default authenticate using a [GITHUB_TOKEN](https://docs.github.com/en/actions/security-guides/automatic-token-authentication) which is generated automatically.
 
@@ -219,7 +231,7 @@ git commit ${GITHUB_SIGNING_OPTION} -am "Automated commit from GitHub Actions: $
 git push
 ```
 
-### AWS CodePipeline
+#### AWS CodePipeline
 
 The cryptographic libraries in the default Amazon Linux 2 distro are very old, and do not support elliptic curve cryptography. When using pre-existing solution elements updating the build container is not always an option. This restricts the GPG key algorithm to RSA. You should use RSA-4096, which is the required minimum for GitHub.
 
@@ -272,10 +284,50 @@ git commit ${GITHUB_SIGNING_OPTION} -am "Automated commit from ${SCRIPT_URL}"
 git push
 ```
 
-## Troubleshooting
+### Troubleshooting
 
-Re-run your git command prefixed with GIT_TRACE=1
+Re-run your git command prefixed with `GIT_TRACE=1`.
+
+A failure to sign a commit is usually because the name or email does not quite match those which were used to generate the GPG key, so git cannot auto-select a key. Ensure that these are indeed consistent. (If you added a comment when creating your GPG key, this *may* cause a mismatch: the comment will be visible when listing your GPG keys, e.g. `RealName (Comment) <EmailAddress>`.) You are able to [force a choice of signing key](https://docs.github.com/en/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key), though this should not be necessary.
+
+## SSH commit signing
+
+1. If you do not already have SSH key access set up on your GitHub account, first [generate a new SSH key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). To create a new SSH key, you need to run the following command. This will generate a new SSH key of the type `ed25519` and associate it with your email address (replace `<my_email_address>` with your actual email address):
+
+    ```shell
+    ssh-keygen -t ed25519 -C "<my_email_address>" -f "~/.ssh/github-signing-key"
+    ```
 
-A failure to sign a commit is usually because the name or email does not quite match those which were used to generate the GPG key, so git cannot auto-select a key. Ensure that these are indeed consistent. (If you added a comment when creating your gpg key, this *may* cause a mismatch: the comment will be visible when listing your gpg keys, e.g. `RealName (Comment) <EmailAddress>`.) You are able to [force a choice of signing key](https://docs.github.com/en/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key), though this should not be necessary.
+    > When you run this command, it will ask you to enter a passphrase. Choose a strong passphrase and make sure to remember it, as you will need to provide it when your key is loaded by the SSH agent.
+
+1. Signing commits with an SSH key is not the default method, so you need to [configure Git](https://docs.github.com/en/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key#telling-git-about-your-ssh-key) accordingly:
+
+    1. Run the following command to instruct Git to use the SSH signing key format, instead of the default GPG:
+    
+        ```shell
+        git config --global gpg.format ssh
+        ```
+    
+    1. Next, specify the private key for Git to use:
+    
+        ```shell
+        git config --global user.signingkey ~/.ssh/github-signing-key
+        ```
+    
+    1. Lastly, instruct Git to sign all of your commits:
+    
+        ```shell
+        git config --global commit.gpgsign true
+        ```
+
+1. [Add the SSH public key to your GitHub account](https://github.com/settings/ssh/new) (`Settings` -> `SSH and GPG keys` -> `New SSH key`)
+
+    1. `Key type` = `Signing Key`
+    1. Copy the contents of your public key file and paste it into the `Key` field.
+
+        ```shell
+        cat ~/.ssh/github-signing-key.pub
+        ```
+    1. `Add SSH key`
 
-If you have already committed and need to retrospectively sign this commit [please follow the instructions here](./retrospective-commit-signing.md).
+1. To ensure your configuration works as expected, make a commit to a branch locally and push it to GitHub. When you view the commit history of the branch on GitHub, [your latest commit](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification#about-commit-signature-verification) should now display a `Verified` tag, which indicates successful signing with your GPG or SSH key.

From abeaf15c86725404790a4946c5fa0f3b6a1544dc Mon Sep 17 00:00:00 2001
From: Kris Bloe <2674722+chrisbloe@users.noreply.github.com>
Date: Fri, 26 Sep 2025 12:13:59 +0100
Subject: [PATCH 17/21] Just formatting

---
 practices/guides/commit-signing.md | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/practices/guides/commit-signing.md b/practices/guides/commit-signing.md
index f301efa4..18fac9f9 100644
--- a/practices/guides/commit-signing.md
+++ b/practices/guides/commit-signing.md
@@ -303,19 +303,19 @@ A failure to sign a commit is usually because the name or email does not quite m
 1. Signing commits with an SSH key is not the default method, so you need to [configure Git](https://docs.github.com/en/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key#telling-git-about-your-ssh-key) accordingly:
 
     1. Run the following command to instruct Git to use the SSH signing key format, instead of the default GPG:
-    
+
         ```shell
         git config --global gpg.format ssh
         ```
-    
+
     1. Next, specify the private key for Git to use:
-    
+
         ```shell
         git config --global user.signingkey ~/.ssh/github-signing-key
         ```
-    
+
     1. Lastly, instruct Git to sign all of your commits:
-    
+
         ```shell
         git config --global commit.gpgsign true
         ```
@@ -328,6 +328,7 @@ A failure to sign a commit is usually because the name or email does not quite m
         ```shell
         cat ~/.ssh/github-signing-key.pub
         ```
+
     1. `Add SSH key`
 
 1. To ensure your configuration works as expected, make a commit to a branch locally and push it to GitHub. When you view the commit history of the branch on GitHub, [your latest commit](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification#about-commit-signature-verification) should now display a `Verified` tag, which indicates successful signing with your GPG or SSH key.

From 069f07d66503d3a665dbe6511a70f894b82445e8 Mon Sep 17 00:00:00 2001
From: Kris Bloe <2674722+chrisbloe@users.noreply.github.com>
Date: Fri, 3 Oct 2025 09:05:19 +0100
Subject: [PATCH 18/21] Changing the recommended encryption and removing SSH
 instructions

Updated the commit signing guide to focus on GPG and ECC methods, and removed SSH signing instructions.
---
 practices/guides/commit-signing.md | 55 +++---------------------------
 1 file changed, 4 insertions(+), 51 deletions(-)

diff --git a/practices/guides/commit-signing.md b/practices/guides/commit-signing.md
index 18fac9f9..26837415 100644
--- a/practices/guides/commit-signing.md
+++ b/practices/guides/commit-signing.md
@@ -1,12 +1,10 @@
 # Git commit signing setup guide
 
-Using GPG, SSH, or S/MIME, you can sign commits and tags locally. These commits and tags are marked as verified on GitHub so other people can be confident that the changes come from a trusted source.
-
-The instructions on this page focus on GPG and SSH.
+Using GPG, SSH, or S/MIME, you can sign commits and tags locally. These commits and tags are marked as verified on GitHub so other people can be confident that the changes come from a trusted source (see the full GitHub documentation [here](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification)).
 
 > You should only set up **one** of these options - **don't attempt to set up GPG and SSH commit signing**!
 
-See the full GitHub documentation [here](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification).
+The instructions on this page focus on the recommended method - GPG.
 
 ## GPG commit signing
 
@@ -38,8 +36,7 @@ If you have already committed and need to retrospectively sign commits, follow t
     gpg --full-generate-key
     ```
 
-    1. Pick `RSA and RSA`, or `RSA (sign only)` (there is no elliptic curve cryptography (ECC) support at the time of writing)
-    1. `keysize` `4096` bits (the minimum accepted for GitHub)
+    1. Pick `ECC (sign and encrypt)` then `Curve 25519` ([Ed25519](https://en.wikipedia.org/wiki/EdDSA#Ed25519) offers the strongest encryption at time of writing)
     1. Select a key expiry time (personal choice)
     1. `Real name` Your GitHub handle
     1. `Email address` Your GitHub account email [listed on your GitHub profile](https://github.com/settings/emails) (you can use the privacy *@users.noreply.github.com* email address): `Settings` -> `Emails` -> `Keep my email addresses private`)
@@ -98,8 +95,7 @@ If you have already committed and need to retrospectively sign commits, follow t
     gpg --full-generate-key
     ```
 
-    1. Pick `RSA and RSA`, or `RSA (sign only)` (there is no elliptic curve cryptography (ECC) support at the time of writing)
-    1. `keysize` = `4096` bits (the minimum accepted for GitHub)
+    1. Pick `ECC (sign and encrypt)` then `Curve 25519` ([Ed25519](https://en.wikipedia.org/wiki/EdDSA#Ed25519) offers the strongest encryption at time of writing)
     1. Select a key expiry time (personal choice)
     1. `Real name` = Your GitHub handle
     1. `Email address` = Your GitHub account email [listed on your GitHub profile](https://github.com/settings/emails) (you can use the privacy *@users.noreply.github.com* email address): `Settings` -> `Emails` -> `Keep my email addresses private`)
@@ -289,46 +285,3 @@ git push
 Re-run your git command prefixed with `GIT_TRACE=1`.
 
 A failure to sign a commit is usually because the name or email does not quite match those which were used to generate the GPG key, so git cannot auto-select a key. Ensure that these are indeed consistent. (If you added a comment when creating your GPG key, this *may* cause a mismatch: the comment will be visible when listing your GPG keys, e.g. `RealName (Comment) <EmailAddress>`.) You are able to [force a choice of signing key](https://docs.github.com/en/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key), though this should not be necessary.
-
-## SSH commit signing
-
-1. If you do not already have SSH key access set up on your GitHub account, first [generate a new SSH key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). To create a new SSH key, you need to run the following command. This will generate a new SSH key of the type `ed25519` and associate it with your email address (replace `<my_email_address>` with your actual email address):
-
-    ```shell
-    ssh-keygen -t ed25519 -C "<my_email_address>" -f "~/.ssh/github-signing-key"
-    ```
-
-    > When you run this command, it will ask you to enter a passphrase. Choose a strong passphrase and make sure to remember it, as you will need to provide it when your key is loaded by the SSH agent.
-
-1. Signing commits with an SSH key is not the default method, so you need to [configure Git](https://docs.github.com/en/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key#telling-git-about-your-ssh-key) accordingly:
-
-    1. Run the following command to instruct Git to use the SSH signing key format, instead of the default GPG:
-
-        ```shell
-        git config --global gpg.format ssh
-        ```
-
-    1. Next, specify the private key for Git to use:
-
-        ```shell
-        git config --global user.signingkey ~/.ssh/github-signing-key
-        ```
-
-    1. Lastly, instruct Git to sign all of your commits:
-
-        ```shell
-        git config --global commit.gpgsign true
-        ```
-
-1. [Add the SSH public key to your GitHub account](https://github.com/settings/ssh/new) (`Settings` -> `SSH and GPG keys` -> `New SSH key`)
-
-    1. `Key type` = `Signing Key`
-    1. Copy the contents of your public key file and paste it into the `Key` field.
-
-        ```shell
-        cat ~/.ssh/github-signing-key.pub
-        ```
-
-    1. `Add SSH key`
-
-1. To ensure your configuration works as expected, make a commit to a branch locally and push it to GitHub. When you view the commit history of the branch on GitHub, [your latest commit](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification#about-commit-signature-verification) should now display a `Verified` tag, which indicates successful signing with your GPG or SSH key.

From 9373fb59bccf9e17eccaa90aecaa8009514454a7 Mon Sep 17 00:00:00 2001
From: Kris Bloe <2674722+chrisbloe@users.noreply.github.com>
Date: Fri, 3 Oct 2025 09:23:41 +0100
Subject: [PATCH 19/21] Correct capitalization of 'public key'

---
 practices/guides/commit-signing.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/practices/guides/commit-signing.md b/practices/guides/commit-signing.md
index 26837415..d8ff8d15 100644
--- a/practices/guides/commit-signing.md
+++ b/practices/guides/commit-signing.md
@@ -47,14 +47,14 @@ If you have already committed and need to retrospectively sign commits, follow t
     1. Review your inputs and press enter `O` to confirm
     1. Define a passphrase for the key
 
-1. Test the key is visible and export the PGP PUBLIC KEY (to your clipboard):
+1. Test the key is visible and export the PGP public key (to your clipboard):
 
     ```bash
     gpg -k # This should list the new key
     gpg --armor --export <my_email_address> | pbcopy
     ```
 
-    > Your PGP PUBLIC KEY is now in your clipboard!
+    > Your PGP public key is now in your clipboard!
 
 1. [Add the public key to your GitHub account](https://github.com/settings/gpg/new) (`Settings` -> `SSH and GPG keys` -> `New GPG key`)
 
@@ -106,14 +106,14 @@ If you have already committed and need to retrospectively sign commits, follow t
     1. Review your inputs and press enter `O` to confirm
     1. A new window called pinentry will appear prompting you to enter a passphrase.
 
-1. Test the key is visible and export the PGP PUBLIC KEY (to your clipboard):
+1. Test the key is visible and export the PGP public key (to your clipboard):
 
     ```bash
     gpg -k # This should list the new key
     gpg --armor --export <my_email_address> | clip
     ```
 
-    > Your PGP PUBLIC KEY is now in your clipboard!
+    > Your PGP public key is now in your clipboard!
 
 1. [Add the public key to your GitHub account](https://github.com/settings/gpg/new) (`Settings` -> `SSH and GPG keys` -> `New GPG key`)
 

From 8b2a05bc76551850814b4db26eb32b9adabcd8da Mon Sep 17 00:00:00 2001
From: Kris Bloe <2674722+chrisbloe@users.noreply.github.com>
Date: Fri, 3 Oct 2025 15:44:51 +0100
Subject: [PATCH 20/21] Suggest using @nhs.net email to enable Smart Commits

---
 practices/guides/commit-signing.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/practices/guides/commit-signing.md b/practices/guides/commit-signing.md
index d8ff8d15..4c6d0871 100644
--- a/practices/guides/commit-signing.md
+++ b/practices/guides/commit-signing.md
@@ -38,10 +38,10 @@ If you have already committed and need to retrospectively sign commits, follow t
 
     1. Pick `ECC (sign and encrypt)` then `Curve 25519` ([Ed25519](https://en.wikipedia.org/wiki/EdDSA#Ed25519) offers the strongest encryption at time of writing)
     1. Select a key expiry time (personal choice)
-    1. `Real name` Your GitHub handle
-    1. `Email address` Your GitHub account email [listed on your GitHub profile](https://github.com/settings/emails) (you can use the privacy *@users.noreply.github.com* email address): `Settings` -> `Emails` -> `Keep my email addresses private`)
+    1. `Real name` = Your GitHub handle
+    1. `Email address` = An email address [registered against your GitHub account](https://github.com/settings/emails) - to enable [Smart Commits](https://nhsd-confluence.digital.nhs.uk/x/SZNYRg#UsingtheGitHubintegrationinJira-SmartCommits) ([Jira/GitHub integration](https://support.atlassian.com/jira-software-cloud/docs/process-issues-with-smart-commits/)), use your `@nhs.net` address
 
-        > If you go for the private email option, consider enabling `Block command line pushes that expose my email`.
+        > If instead you opt for the private *@users.noreply.github.com* email address, consider enabling `Block command line pushes that expose my email`.
 
     1. Avoid adding a comment (this *may* prevent git from auto-selecting a key - see Troubleshooting section below)
     1. Review your inputs and press enter `O` to confirm
@@ -98,9 +98,9 @@ If you have already committed and need to retrospectively sign commits, follow t
     1. Pick `ECC (sign and encrypt)` then `Curve 25519` ([Ed25519](https://en.wikipedia.org/wiki/EdDSA#Ed25519) offers the strongest encryption at time of writing)
     1. Select a key expiry time (personal choice)
     1. `Real name` = Your GitHub handle
-    1. `Email address` = Your GitHub account email [listed on your GitHub profile](https://github.com/settings/emails) (you can use the privacy *@users.noreply.github.com* email address): `Settings` -> `Emails` -> `Keep my email addresses private`)
+    1. `Email address` = An email address [registered against your GitHub account](https://github.com/settings/emails) - to enable [Smart Commits](https://nhsd-confluence.digital.nhs.uk/x/SZNYRg#UsingtheGitHubintegrationinJira-SmartCommits) ([Jira/GitHub integration](https://support.atlassian.com/jira-software-cloud/docs/process-issues-with-smart-commits/)), use your `@nhs.net` address
 
-        > If you go for the private email option, consider enabling `Block command line pushes that expose my email`.
+        > If instead you opt for the private *@users.noreply.github.com* email address, consider enabling `Block command line pushes that expose my email`.
 
     1. Avoid adding a comment (this *may* prevent git from auto-selecting a key - see Troubleshooting section below)
     1. Review your inputs and press enter `O` to confirm

From 2ec33a658fad5dcc26ee4c7aa02c43b71d6a9d11 Mon Sep 17 00:00:00 2001
From: Kris Bloe <2674722+chrisbloe@users.noreply.github.com>
Date: Tue, 7 Oct 2025 16:02:11 +0100
Subject: [PATCH 21/21] Update --show-signature examples

---
 practices/guides/commit-signing.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/practices/guides/commit-signing.md b/practices/guides/commit-signing.md
index 4c6d0871..939ebafa 100644
--- a/practices/guides/commit-signing.md
+++ b/practices/guides/commit-signing.md
@@ -82,6 +82,7 @@ If you have already committed and need to retrospectively sign commits, follow t
         $ git log --show-signature -1
         ...
         gpg: Good signature from "<github_handle> <<my_email_address>>" [ultimate]
+        Author: <github_handle> <<my_email_address>>
         ...
         ```
 
@@ -187,6 +188,7 @@ If you have already committed and need to retrospectively sign commits, follow t
         $ git log --show-signature -1
         ...
         gpg: Good signature from "<github_handle> <<my_email_address>>" [ultimate]
+        Author: <github_handle> <<my_email_address>>
         ...
         ```