This guide will show you how you can configure your development setup to automatically sign git commits using GPG and link your GPG key with GitHub.

Commit signing with GPG proves your commits are actually from you and haven't been messed with—anyone can fake a Git author name, but they can't fake your cryptographic signature. The catch is that your private key is everything: if someone gets it, they can sign commits as you and potentially slip malicious code into your projects while looking completely legitimate. Keep your GPG key secure with a strong passphrase and treat it like any other critical credential, because once it's compromised, your entire signing credibility goes with it.

Make sure you follow the Prerequisites, How To Contribute (microsoft/vscode) guide.

• Install Gpg4win

• Check the path of your gpg version. Depending on whether you installed the 32-bit or 64-bit version it will be either in "Program Files (x86)" or in "Program Files":

where gpg
> C:\Program Files\GnuPG\bin\gpg.exe

• Make sure Git uses that GPG version:

git config --global gpg.program "C:\Program Files (x86)\GnuPG\bin\gpg.exe"

Install the necessary tools and configure GPG:

First, install Homebrew (https://brew.sh/). Then run the following commands:

brew install gpg2 gnupg pinentry-mac
mkdir -p ~/.gnupg
echo "pinentry-program $(brew --prefix)/bin/pinentry-mac" >> ~/.gnupg/gpg-agent.conf
echo "use-agent" >> ~/.gnupg/gpg.conf
echo 'export GPG_TTY=$(tty)' >> ~/.bash_profile # replace with ~/.zprofile if using ZSH

Restart your machine. Yes, really.

There are two options: generate or copy an existing key.

Windows: make sure you're using a Command Prompt or PowerShell instead of the Git Bash shell. Make sure the right GPG is being used:

C:\Users\User> where gpg
C:\Program Files (x86)\GnuPG\bin\gpg.exe

Run:

gpg --full-generate-key

With the following options:

• Kind of key: RSA and RSA (default)
• Keysize: 4096
• Expiration: 0 (does not expire)
• Real Name: use your real name
• Email address: use your Microsoft email address
  • Note: If you use the setting "Keep my email addresses private" (in the GitHub Email Settings), you might need to set the private email address listed there as the email address on this step.
• Comment: Key for signing commits for Microsoft
• Passphrase: Pick a long, secure passphrase, which you'll easily remember.

In the following example, DF536B632D7967F9 is the key ID:

$ gpg --list-secret-keys --keyid-format LONG
gpg: checking the trustdb
gpg: marginals needed: 3  completes needed: 1  trust model: pgp
gpg: depth: 0  valid:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 1u
/home/joao/.gnupg/pubring.kbx
-----------------------------
sec   rsa4096/DF536B632D7967F9 2021-04-07 [SC]
      1D0FC7C0350BB570143C934FDF536B632D7967F9
uid                 [ultimate] Joao Moreno (Key for signing commits for Microsoft) <[email protected]>
ssb   rsa4096/41FC60C87D442095 2021-04-07 [E]

You can use your key ID to get your public key:

$ gpg --armor --export DF536B632D7967F9
-----BEGIN PGP PUBLIC KEY BLOCK-----
...
-----END PGP PUBLIC KEY BLOCK-----

Alternatively, you can export a existing key from another machine, by replacing KEYID with your key ID:

gpg --export-secret-keys -a KEYID > my-key.asc

Then, copy it into your machine and import it:

gpg --import my-key.asc

Finally, set its trust level to ultimate:

$ gpg --edit-key KEYID
gpg> trust
Your decision? 5

Follow the Adding a new GPG key to your GitHub account guide to give GitHub your public key.

Run the following, replacing KEYID with your key ID:

git config --global user.signingkey KEYID
git config --global commit.gpgsign true

Git will now sign all commits by default. Signing requires access to your GPG key, which requires the passphrase. Follow the respective platform specific steps below to decrease pain.

Create a dummy commit on a sample local repository. You should see a prompt for your key's passphrase:

Enter your GPG key passphrase and hit OK. In order to avoid typing the passphrase on every commit, you can make GPG remember it for 8 hours or until the next reboot:

1. Launch Kleopatra
2. Click Settings > Configure Kleopatra...
3. Navigate to GnuPG System > Private Keys
4. Change Expire cached PINs after N seconds to 28800

Create a dummy commit on a sample local repository. You should see a prompt for your key's passphrase:

In order to avoid typing the passphrase on every commit, just select Save in Keychain. That should've been the last time you typed the passphrase.

Create a dummy commit on a sample local repository. You should see a prompt for your key's passphrase:

Enter your GPG key passphrase and hit OK. In order to avoid typing the passphrase on every commit, you can make GPG remember it for 8 hours or until the next reboot:

mkdir -p ~/.gnupg
echo "default-cache-ttl 28800" >> ~/.gnupg/gpg-agent.conf

Note: Apparently, it's a moot point to select Save in password manager, because problems 🙄. Every time you reboot your machine you'll always be asked for your passphrase. If you select Save in password manager, you'll also be asked for your Keyring password every time you reboot, so it's best not to do it.

Make sure that if you push a signed commit to GitHub it appears as Verified:

You should guard this key as well as you guard your SSH key. While an SSH key can easily be replaced by another, since it only affects the login to Github, a GPG key will forever be associated with your commits. This means that as soon as you remove the GPG key from GitHub, because say you replaced it with another, the commits won't appear Verified any longer.

One of the best ways to store a backup or even to use the key directly is to use a YubiKey. You can store a copy of your key in a YubiKey, serving as a backup. Or you can even store the only copy of your key in it and always require your YubiKey when creating commits. This definitely increases security but with the obvious added inconvenience of always needing your YubiKey around when committing changes changes. Learn more.

Codespaces will use a different GPG key, but it will indeed sign all your commits automatically, so they appear as verified on GitHub. Learn more.

• GitHub: About commit signature verification
• GitHub: Signing commits
• GnuPG: GnomeKeyring
• macOS: Methods of Signing with GPG
• How (and why) to sign Git commits