-
-
Notifications
You must be signed in to change notification settings - Fork 77
Signing Git commits using GPG keys
Wiki ▸ GPG and PGP ▸ Signing Git commits using GPG keys
Signing Git commits using GPG keys is the process of using a cryptographic identity to assert that a given change to a piece of software was made by a given individual, organization, or other entity. This is accomplished by associating a (cryptographic) digital signature with the commit (software patch) itself. Other users of the software (like you) can then validate that the software being patched was modified only by sources they trust.
🔰📖 GPG is also known as PGP. For the purposes of this guide, we will be referring to the tool as GPG. For further information on the difference between the initialisms, see GPG and PGP.
🔰 💡 This procedure requires the use of a command line. If you are unfamiliar with the command line, we recommend you take some time to work through the excellent Foundations: Command Line Basics course offered for free by Tech Learning Collective, or another tutorial series such as Taming the Terminal.
In brief, to sign Git commits with a GPG key, you must first have (or generate) a GPG key pair. Each GPG key pair is uniquely identified by a fingerprint (also called a key ID), which is represented by a string of 40 hexadecimal characters. The GPG keys you have access to are stored on your computer in a structure called a GPG keyring. To view your keyring from a command line you invoke the gpg
command-line program with the --list-keys
or --list-secret-keys
options to list all keys in your keyring or only the keys to which you have an associated private ("secret") part, respectively.
Once you have a GPG key, you must then inform the git
program on your computer to use the key of your choice when signing commits. Finally, you must ensure that your invocations to the git commit
command tell Git to sign the commit. This is most easily accomplished by aliasing git commit
to git commit --gpg-sign
or an equivalent.
Additionally, if you plan on using this key for a project hosted by GitHub.com, you will need a GitHub account. See our New member orientation guide § GitHub advice for instructions on creating a personal and/or pseudonymous GitHub account.
The following outlines the exact process for generating a good GPG keypair, followed by telling git
which one to use, with operational security considerations included. We assume you will be performing these steps from a laptop or desktop computer. You can generate GPG keys from mobile devices such as Android smartphones, but we find it difficult to write code from a mobile device. :)
Before you can use a GPG key, you must have one to use. This section describes the process for generating an OpenPGP-compatible keypair (i.e., a GPG keypair) that can be used by all standards-compliant GPG or PGP programs, such as git
.
🔰
⚠️ Your GPG key, just like the username and password combination to your account, can reveal your identity (because it is an identity). Therefore, we recommended making different GPG keys for each of your GitHub (or GitLab, etc.) accounts that you wish to compartmentalize from one another. In other words, do not use your personal GPG key with your pseudonymous GitHub account, or vice versa. We are, of course, assuming you probably don't want to sign your day job's code commits with your anti-cop GPG key, unless your boss is down. 🏴
- Ensure you have the
gpg
(orgpg2
) program installed. In a terminal, enter:gpg --version
🔰 💡 If you do not have a
gpg
binary in your shell's search path, check forgpg2 --version
, as some systems install the program under this slightly different name. If you prefer to usegpg2
overgpg
, you'll also need to informgit
to use this alternative name. This can be accomplished by setting thegpg.program
Git configuration option:git config --global gpg.program gpg2
- If you do not already have
gpg
orgpg2
, install it:- macOS users can install GPG via MacPorts using
port install gnupg2
, via Homebrew usingbrew install gnupg
, or with a graphical user interface from GPGTools.org. - GNU/Linux users can install GPG via their operating system's default package repositories. Users of Debian-based GNU/Linux distributions such as Ubuntu:
sudo apt update && sudo apt install gnupg2
- Windows users can install GPG4Win, which installs a command line executable as well as equivalent GUI tools.
- macOS users can install GPG via MacPorts using
- If you do not already have
- Initiate the interactive key generation process, which will prompt you for specifics about your desired new key:
gpg --full-gen-key
- Select a type of key. We suggest making an RSA keypair (typically also the default).
💡 It is possible to sign commits with different types of GPG keys, however, as of this writing, GitHub itself suggests using RSA keys that are 4096 bits long. A 4096-bit long RSA key is secure enough for these purposes.
- Select a key length. Type in
4096
and hitEnter
to make a 4096-bit long key. - Select how long you want this key to be valid for. Pick a time frame that makes sense for the use of the key; 2 years, for example, is long enough to be useful but not so long as to risk perpetual use if a vulnerability should be found or a compromise should occur later on.
- Confirm your chosen expiry date.
- Enter the details of your chosen cryptographic identity. If you're using this key to sign commits on a public repository, or on GitHub generally, try to match the information that you've already given GitHub (or whatever service), so that you're not unnecessarily giving out more personal information than needed.
- Finally, choose a (strong!) password to protect the private portion of your GPG keypair.
🔰💡 Choosing strong passwords is always important, so we strongly encourage the use of a password/secrets management application such as Bitwarden, KeePass, etc. Most password managers also feature the ability to generate strong passwords.
Repeat the above step for each independent identity you wish to create. For instance, if you have a distinct "professional" GitHub account separate from a "personal" or "activist" GitHub account, make a dedicated GPG key for each account. Take care not to pollute one of your identities with artifacts from the other. At worst, this will de-anonymize you. At best, it will offer an adversary additional information with which to correlate your behaviors across your various (no-longer-secret) identities.
You can now sign commits with your newly generated key by invoking git
with the -S
or --gpg-sign
option, passing your key ID as the value to the -S
or --gpg-sign
options. For example:
git commit --gpg-sign=C42F2F04C42D489E23DD71CE07EFAA28AB94BC85
Continue to the next steps to simplify this command line quite a bit.
Once you have a GPG keypair with which to use to sign commits, you may want to configure your installation of the Git source code management tool, or a specific Git repository, to automatically use that key when you commit changes to the code.
💡 This step is optional, but recommended.
- Find the fingerprint of the GPG key you'd like to use to sign commits with.
gpg --list-secret-keys --keyid-format LONG
- Navigate to the folder containing your Git project.
- Inform
git
of the GPG key you'd like to use to sign commits to this project. Assuming your GPG key ID isC42F2F04C42D489E23DD71CE07EFAA28AB94BC85
, you would invokegit config
as follows:git config user.signingKey C42F2F04C42D489E23DD71CE07EFAA28AB94BC85
🔰
⚠️ Many Git and GPG guides will tell you to use the commandgit config
with the--global
option to write the configuration into your home directory's.gitconfig
file. Their advice is intened to simplify your use ofgit
, but means that your key selection will apply by default (i.e., every commit will be signed using this key unless a specific project's.git/config
file overrides that selection). This can be a potential operational security risk if you're trying to keep one GitHub account relatively separate from another. This is why we prefer the use of per-repository configurations over user account-wide ("global") configurations.
You can now sign commits with your newly generated key by invoking git
with the -S
or --gpg-sign
option, without the need to pass your key ID on the command line. For example:
git commit -S
The above is enough to automatically select your configured signing key and create a GPG-signed commit.
To further reduce repetitive typing, some people choose to set up a Git command alias.
💡 This step is purely optional.
- Navigate to the folder containing your Git project.
- Configure a
git
alias:git config alias.cs "commit -S"
You can now sign commits with your newly generated key by invoking git
with your new alias:
git cs
The above is now enough to enable GPG commit signing with your pre-configured chosen key.
The NYC chapter of the Anarcho-Tech Collective provides technological and digital infrastructure support services to anti-fascist, anti-racist, and anti-capitalist organizations in New York City. See our Activities and events page for details. Read our Welcome guides to get involved.
We appreciate your support to help us do what we do. If you have the means, please donate BitCoin to 17ByVbkM6mf7bytqWRFwzjqradBkmVh4Tr
.
Found an error in these pages? Please let us know by submitting a new issue ticket.