You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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)).
11
4
12
-
## From Workstations
5
+
> You should only set up **one** of these options - **don't attempt to set up GPG and SSH commit signing**!
13
6
14
-
### macOS
7
+
The instructions on this page focus on the recommended method - GPG.
15
8
16
-
- Install the [Brew package manager](https://brew.sh)
9
+
## GPG commit signing
17
10
18
-
```bash
19
-
brew upgrade
20
-
brew install gnupg pinentry-mac
21
-
gpg --full-generate-key
22
-
```
11
+
### From Workstations
23
12
24
-
- Accept the defaults, Curve 25519 etc.
25
-
- Enter your GitHub account name as the Real Name
26
-
- Enter your GitHub account email as the Email Address
27
-
- Avoid adding a comment (this *may* prevent git from auto-selecting a key - see Troubleshooting section below)
28
-
- You can use the privacy *@users.noreply.github.com* email address listed in the GitHub profile: *Settings > Email*
29
-
- Define a passphrase for the key and keep it in your password manager
13
+
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).
30
14
31
-
```bash
32
-
gpg --armor --export ${my_email_address}| pbcopy
33
-
```
15
+
#### macOS
34
16
35
-
- 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*
36
-
- Paste it in
17
+
1. Install `gnupg` & `pinentry-mac` with [Brew](https://brew.sh):
37
18
38
-
```bash
39
-
git config --global user.email ${my_email_address}# same one used during key generation
40
-
git config --global user.name ${my_username}
41
-
git config --global commit.gpgsign true
42
-
sed -i '''/^export GPG_TTY/d'~/.zshrc
43
-
echoexport GPG_TTY=\$\(tty\)>>~/.zshrc
44
-
source~/.zshrc
45
-
PINENTRY_BIN=$(whereis -q pinentry-mac)
46
-
sed -i '''/^pinentry-program/d'~/.gnupg/gpg-agent.conf
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.
33
+
1. Create a new GPG key:
52
34
53
-
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*.
35
+
```bash
36
+
gpg --full-generate-key
37
+
```
54
38
55
-
### Windows
39
+
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)
40
+
1. Select a key expiry time (personal choice)
41
+
1. `Real name` = Your GitHub handle
42
+
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
56
43
57
-
- Install [Git for Windows](https://git-scm.com/download/win), which includes Bash and GnuPG
58
-
- Right-click on the Desktop > *Git Bash Here*
44
+
> If instead you opt for the private *@users.noreply.github.com* email address, consider enabling `Block command line pushes that expose my email`.
59
45
60
-
```bash
61
-
gpg --full-generate-key
62
-
```
46
+
1. Avoid adding a comment (this *may* prevent git from auto-selecting a key - see Troubleshooting section below)
47
+
1. Review your inputs and press enter `O` to confirm
48
+
1. Define a passphrase for the key
63
49
64
-
- Pick *RSA and RSA*, or *RSA (sign only)* - there is no elliptic curve cryptography (ECC) support at the time of writing
65
-
- Set key size to 4096 bit, the minimum accepted for GitHub
66
-
- Enter your GitHub account name as the Real Name
67
-
- Enter your GitHub account email as the Email Address
68
-
- Avoid adding a comment (this *may* prevent git from auto-selecting a key - see Troubleshooting section below)
69
-
- You can use the privacy *@users.noreply.github.com* email address listed in the GitHub profile: *Settings > Email*
70
-
- Define a passphrase for the key and keep it in your password manager
50
+
1. Test the key is visible and export the PGP public key (to your clipboard):
71
51
72
-
```bash
73
-
gpg --armor --export ${my_email_address}| clip
74
-
```
52
+
```bash
53
+
gpg -k # This should list the new key
54
+
gpg --armor --export <my_email_address> | pbcopy
55
+
```
75
56
76
-
- 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*
77
-
- Paste it in
57
+
> Your PGP public key is now in your clipboard!
78
58
79
-
```bash
80
-
git config --global user.email ${my_email_address}# same one used during key generation
81
-
git config --global user.name ${my_username}
82
-
git config --global commit.gpgsign true
83
-
```
59
+
1. [Add the public key to your GitHub account](https://github.com/settings/gpg/new) (`Settings` ->`SSH and GPG keys` ->`New GPG key`)
60
+
61
+
> Note the `Key ID` as you'll need this in the next step.
62
+
63
+
1. Set your local git config to use GPG signing:
64
+
65
+
```bash
66
+
git config --global user.email <my_email_address> # same one used during key generation
67
+
git config --global user.name <github_handle>
68
+
git config --global user.signingkey <key_id>
69
+
git config --global commit.gpgsign true
70
+
git config --global tag.gpgsign true
71
+
```
72
+
73
+
1. Test it works:
74
+
75
+
1. Create a temporary branch of your favourite repository.
76
+
1. Make an inconsequential whitespace change.
77
+
1. Commit the change.
78
+
1. You will be prompted for your GPG key passphrase - optionally select to add it to the macOS Keychain.
79
+
1. Check the latest commit shows a successful signing:
80
+
81
+
```bash
82
+
$ git log --show-signature -1
83
+
...
84
+
gpg: Good signature from "<github_handle> <<my_email_address>>" [ultimate]
85
+
Author: <github_handle> <<my_email_address>>
86
+
...
87
+
```
88
+
89
+
#### Windows/WSL
90
+
91
+
1. Install (as administrator) [Git for Windows](https://git-scm.com/download/win) (which includes Bash and GnuPG)
92
+
1. Open `Git Bash`
93
+
1. Create a new GPG key:
94
+
95
+
```bash
96
+
gpg --full-generate-key
97
+
```
98
+
99
+
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)
100
+
1. Select a key expiry time (personal choice)
101
+
1. `Real name` = Your GitHub handle
102
+
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
103
+
104
+
> If instead you opt for the private *@users.noreply.github.com* email address, consider enabling `Block command line pushes that expose my email`.
105
+
106
+
1. Avoid adding a comment (this *may* prevent git from auto-selecting a key - see Troubleshooting section below)
107
+
1. Review your inputs and press enter `O` to confirm
108
+
1. A new window called pinentry will appear prompting you to enter a passphrase.
84
109
85
-
When you commit you will be prompted to enter the GPG key passphrase into a Pinentry window.
110
+
1. Test the key is visible and export the PGP public key (to your clipboard):
86
111
87
-
## From Pipelines
112
+
```bash
113
+
gpg -k # This should list the new key
114
+
gpg --armor --export <my_email_address> | clip
115
+
```
88
116
89
-
### GitHub Actions
117
+
> Your PGP public key is now in your clipboard!
118
+
119
+
1. [Add the public key to your GitHub account](https://github.com/settings/gpg/new) (`Settings` -> `SSH and GPG keys` -> `New GPG key`)
120
+
121
+
> Note the `Key ID` as you'll need this in the next step.
122
+
123
+
1. Set your local git config to use GPG signing:
124
+
125
+
```bash
126
+
git config --global user.email <my_email_address># same one used during key generation
127
+
git config --global user.name <github_handle>
128
+
git config --global user.signingkey <key_id>
129
+
git config --global commit.gpgsign true
130
+
git config --global tag.gpgsign true
131
+
```
132
+
133
+
1. Now your key is created, make it available within Windows:
1. Test the key is visible and set your local git config to use GPG signing:
169
+
170
+
```bash
171
+
gpg -k # This should list the new key
172
+
git config --global user.email <my_email_address> # same one used during key generation
173
+
git config --global user.name <github_handle>
174
+
git config --global user.signingkey <key_id>
175
+
git config --global commit.gpgsign true
176
+
git config --global tag.gpgsign true
177
+
```
178
+
179
+
1. Test it works:
180
+
181
+
1. Create a temporary branch of your favourite repository.
182
+
1. Make an inconsequential whitespace change.
183
+
1. Commit the change.
184
+
1. You will be prompted for your GPG key passphrase.
185
+
1. Check the latest commit shows a successful signing:
186
+
187
+
```bash
188
+
$ git log --show-signature -1
189
+
...
190
+
gpg: Good signature from "<github_handle> <<my_email_address>>" [ultimate]
191
+
Author: <github_handle><<my_email_address>>
192
+
...
193
+
```
194
+
195
+
### From Pipelines
196
+
197
+
#### GitHub Actions
90
198
91
199
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.
92
200
@@ -97,7 +205,7 @@ The workflow would then use a Personal Access Token, stored with the GPG private
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.
127
235
@@ -138,7 +246,7 @@ if [[ ${BOT_SSH_KEY} != "None" ]]; then
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.
287
+
Re-run your git command prefixed with `GIT_TRACE=1`.
182
288
183
-
If you have already committed and need to retrospectively sign this commit [please follow the instructions here](./retrospective-commit-signing.md).
289
+
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.
0 commit comments