DEV Community

loading...

Signing Git Commits/tags with GPG Keys

Alpha Olomi
A software engineer aimed at helping other using software technologies.
・4 min read

Using GPG or S/MIME, you can sign tags and commits locally. These tags or commits are marked as verified on GitHub so other people can trust that the changes come from a trusted source.

image

If a commit or tag has a signature that cannot be verified, GitHub marks the commit or tag as unverified.

GPG commit signature verification

You can use GPG to sign commits with a GPG key that you generate yourself.

GitHub uses OpenPGP libraries to confirm that your locally signed commits and tags are cryptographically verifiable against a public key you have added to your GitHub account.

To sign commits using GPG and have those commits verified on GitHub, follow these steps:

  1. Check for existing GPG keys
  2. Generate a new GPG key
  3. Add a new GPG key to your GitHub account
  4. Tell Git about your signing key
  5. Sign commits and/or tags

1. Check for existing GPG keys

If you have multiple GPG keys, you need to tell Git which one to use.

  • Open Terminal.

Use the gpg --list-secret-keys --keyid-format LONG command to list GPG keys for which you have both a public and private key. A private key is required for signing commits or tags.

gpg --list-secret-keys --keyid-format LONG
Enter fullscreen mode Exit fullscreen mode

2. Generating a GPG key

If you are on version 2.1.17 or greater, paste the text below to generate a GPG key pair.

$ gpg --full-generate-key

Enter fullscreen mode Exit fullscreen mode

If you are not on version 2.1.17 or greater, the gpg --full-generate-key command doesn't work. Paste the text below and skip to step 6.

$ gpg --default-new-key-algo rsa4096 --gen-key
Enter fullscreen mode Exit fullscreen mode
  • At the prompt, specify the kind of key you want, or press Enter to accept the default RSA and RSA.
  • Enter the desired key size. Your key must be at least 4096 bits.
  • Enter the length of time the key should be valid. Press Enter to specify the default selection, indicating that the key doesn't expire
  • Verify that your selections are correct.
  • Enter your user ID information.

Note: When asked to enter your email address, ensure that you enter the verified email address for your GitHub account. To keep your email address private, use your GitHub-provided no-reply email address.

  • Type a secure passphrase.

  • Use the gpg --list-secret-keys --keyid-format LONG command to list GPG keys for which you have both a public and private key. A private key is required for signing commits or tags.

$ gpg --list-secret-keys --keyid-format LONG
Enter fullscreen mode Exit fullscreen mode

Note: Some GPG installations on Linux may require you to use gpg2 --list-keys --keyid-format LONG to view a list of your existing keys instead. In this case you will also need to configure Git to use gpg2 by running git config --global gpg.program gpg2.

From the list of GPG keys, copy the GPG key ID you'd like to use. In this example, the GPG key ID is 3AA5C34371567BD2:

$ gpg --list-secret-keys --keyid-format LONG
/home/alpha/.gnupg/secring.gpg
------------------------------------
sec   4096R/3AA5C34371567BD2 2020-01-10 [expires: 2027-01-10]
uid                          Alpha 
ssb   4096R/42B317FD4BA89E7A 2020-01-10
Enter fullscreen mode Exit fullscreen mode
  • Paste the text below, substituting in the GPG key ID you'd like to use. In this example, the GPG key ID is 3AA5C34371567BD2:
$ gpg --armor --export 3AA5C34371567BD2
# Prints the GPG key ID, in ASCII armor format
Enter fullscreen mode Exit fullscreen mode
  • Copy your GPG key, beginning with -----BEGIN PGP PUBLIC KEY BLOCK----- and ending with -----END PGP PUBLIC KEY BLOCK-----.

3. Add a new GPG key to your GitHub account

GitHub supports several GPG key algorithms. If you try to add a key generated with an unsupported algorithm, you may encounter an error.

  • Adding a GPG key

Image of User Acc

  • In the user settings sidebar, click SSH and GPG keys.

Authentication keys

  • Click New GPG key.

GPG Key button

  • In the "Key" field, paste the GPG key you copied when you generated your GPG key.

The key field

  • Click Add GPG key.

The Add key button

  • To confirm the action, enter your GitHub password.

4. Tell Git about your signing key

  • Use the gpg --list-secret-keys --keyid-format LONG command to list GPG keys for which you have both a public and private key. A private key is required for signing commits or tags.

From the list of GPG keys, copy the GPG key ID you'd like to use. In this example, the GPG key ID is 3AA5C34371567BD2:

$ git config --global user.signingkey 3AA5C34371567BD2
Enter fullscreen mode Exit fullscreen mode
  • To add your GPG key to your bash profile, paste the text below:
$ test -r ~/.bash_profile && echo 'export GPG_TTY=$(tty)' >> ~/.bash_profile
$ echo 'export GPG_TTY=$(tty)' >> ~/.profile
Enter fullscreen mode Exit fullscreen mode

5. Sign commits and/or tags

When committing changes in your local branch, add the -S flag to the git commit command:

$ git commit -S -m your commit message
# Creates a signed commit
Enter fullscreen mode Exit fullscreen mode

NOTE: When using GPG, after you create your commit, provide the passphrase you set up when you generated your GPG key.

When you've finished creating commits locally, push them to your remote repository on GitHub:

$ git push
# Pushes your local commits to the remote repository
Enter fullscreen mode Exit fullscreen mode
  • On GitHub, navigate to your pull request.

  • On the pull request, click Commits.

Commits tab on a pull request

  • To view more detailed information about the verified signature, click Verified.

Credits

  • Image From Github

More

Discussion (2)

Collapse
chrisngure2599 profile image
Chris Ngure

Wow! Thats nice Alpha!

Collapse
alphaolomi profile image
Alpha Olomi Author

thanks Chris