Revise GPG commit signing guide for macOS & Windows #361
Conversation
Updated instructions for GPG key generation and configuration on macOS and Windows. Also updated GitHub Actions checkout action version.
chrisbloe
changed the title
Updated email and handle placeholders in GPG signing instructions for clarity.
Updated note formatting for clipboard instructions.
Updated Windows section to include WSL in commit signing guide.
Updated the heading for Windows instructions to include WSL.
…in the UI Removed table of contents from the commit signing guide.
Corrected typos in the commit-signing guide regarding whitespace and availability instructions.
Expanded the commit signing guide to include SSH signing instructions and troubleshooting tips.
practices/guides/commit-signing.md
Outdated
|
|
||
| - Install [Git for Windows](https://git-scm.com/download/win), which includes Bash and GnuPG | ||
| - Right-click on the Desktop > *Git Bash Here* | ||
| 1. Pick `RSA and RSA`, or `RSA (sign only)` (there is no elliptic curve cryptography (ECC) support at the time of writing) |
There was a problem hiding this comment.
Can we suggest the ECDSA (over Curve25519) algorithm to be used as default? It's considered being more modern and more often used these days.
There was a problem hiding this comment.
When I run: gpg --full-generate-key
I get the following output:
╰─ gpg --full-generate-key
gpg (GnuPG) 2.4.8; Copyright (C) 2025 g10 Code GmbH
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Please select what kind of key you want:
(1) RSA and RSA
(2) DSA and Elgamal
(3) DSA (sign only)
(4) RSA (sign only)
(9) ECC (sign and encrypt) *default*
(10) ECC (sign only)
(14) Existing key from card
Your selection? 9
Please select which elliptic curve you want:
(1) Curve 25519 *default*
(4) NIST P-384
(6) Brainpool P-256
Your selection? 1
Please specify how long the key should be valid.
0 = key does not expire
<n> = key expires in n days
<n>w = key expires in n weeks
<n>m = key expires in n months
<n>y = key expires in n years
Key is valid for? (0)
practices/guides/commit-signing.md
Outdated
| 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) |
There was a problem hiding this comment.
Can we suggest the ECDSA (over Curve25519) algorithm to be used as default? (same as on macOS version)
practices/guides/commit-signing.md
Outdated
|
|
||
| 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 |
There was a problem hiding this comment.
Do we need to include the SSH flavour of commit signing? One downside is that SSH keys don’t support expiry, which reduces key lifecycle control. The preference would be to document a single recommended method in the framework for consistency.
There was a problem hiding this comment.
I'd added this as it was in the other page migrated over, but I agree it's not the recommended, so have taken it out.
There was a problem hiding this comment.
They don't support automated expiry, but you can expire them. There's an outstanding question as to what it is that we actually expect from signed commits - I think people might be expecting more from them than they can actually deliver, and in our context I'm not sure that SSH keys are meaningfully less good than GPG keys. They're certainly easier to configure.
There was a problem hiding this comment.
See https://security.stackexchange.com/questions/14718/does-openpgp-key-expiration-add-to-security for a bit of discussion on this. The short version is that key expiry dates don't buy you very much, so if you want the practical effect of key expiry then you need to be actively revoking keys and that puts you into a manual process anyway. Plus you need to be aware that there will then be commits in the history which are signed with a now revoked key; if you aren't in control of why that key was revoked (which you're not, when someone leaves) then you can't distinguish between "expired with time before a problem happened" and "known to have been leaked in a hack, potentially used to maliciously sign historical commits".
Updated the commit signing guide to focus on GPG and ECC methods, and removed SSH signing instructions.
| 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` = 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 |
There was a problem hiding this comment.
Looks good — only caveat is that a few Jira users might not have a Confluence account, so the link might not resolve for them, however, that is pretty rare!
|
4 participants
Updated instructions for GPG key generation and configuration on macOS and Windows. Also updated GitHub Actions checkout action version.