How to setup SSH & GPG keys for git

Introduction

Recently, I was in the situation that I wanted to set up a new git repository (independent of hosting service like GitHub or GitLab) with keys for security and verification. I had to look it up and piece the process together, so I decided to write it down here once and for all, for myself and possibly other people, who come looking.

SSH

Using SSH keys is a beautiful mixture of security and convenience. As a user, I do not need to enter my password all the time, which leads to me using more secure passwords (because I am lazy, as are others). From a security standpoint, the key can be easily disabled should it get lost or stolen or whatever.

These keys are also very valuable beyond git, as they can be used for SSH (duh) connections to other computers without entering passwords ever again. ¹

Creating an SSH key

If you already have an SSH key that you want to use, just skip to the next section. Otherwise, simply run the following command:

1

ssh-keygen -t ed25519 -C "your_email@example.com"

Specify the location and filename for the new key, if you have more than one. Choose a passphrase for added security, if you want to.

Set up your git hosting service

Copy the contents of the file with your chosen name and the postfix .pub (for public) to your clipboard and log into GitHub/GitLab/Gitea/whatever. Somewhere in the settings there is an option to add the SSH key, the location varies depending on the service. Here are some guides:

• Adding a new SSH key to your GitHub account
• Add an SSH key to your GitLab account
• Gitea: Profile -> Settings -> SSH/GPG Keys (did not find an official guide, but it is very easy)

Setting up git

To make sure that git uses the SSH key for authentication, go to the git repository in question and run the following command:

1

git config --local ssh.coreCommand "ssh -i ~/.ssh/id_rsa_example -F /dev/null"

Replace id_rsa_example with the path to your (private) key file. This works with existing local git repositories, if you want to clone one, you can do it like this:

1
2
3
4

git clone -c "core.sshCommand=ssh -i ~/.ssh/id_rsa_example -F /dev/null" git@github.com:example/example.git
cd example/
git pull
git push

Check this StackOverflow discussion for more discussion and explanations.

GPG

With GPG keys git commits can be signed. In theory, I can assume any identity in my git commits:

1
2

git config --local user.name "<ANY NAME>"
git config --local user.email "<ANY EMAIL ADDRESS>"

This does not have to match my GitHub credentials, so the name and email address associated with a commit can really be anything. In most cases, this will probably not be a concern, but GPG keys are an easy fix. Providers like GitHub or GitLab show a small Verified badge next to a commit to show that was really created by the associated email address.

Creating a GPG key

If you already have a GPG key that you want to use, then simply skip to the next section. Otherwise follow the following steps:

1

gpg --full-generate-key

You can simply accept the defaults.

Set up your git hosting service

Similar to the SSH key management above, GPG keys can be added to GitHub etc. accounts. Usually it is even on the same page.

First, list the long form of the GPG keys:

1

gpg --list-secret-keys --keyid-format=long

The output will look something like this:

1
2
3
4
5
6

$ gpg --list-secret-keys --keyid-format=long
/Users/hubot/.gnupg/secring.gpg
------------------------------------
sec   4096R/3AA5C34371567BD2 2016-03-10 [expires: 2017-03-10]
uid                          Hubot <hubot@example.com>
ssb   4096R/4BB6D45482678BE3 2016-03-10

Get the private key by exporting based on the key id (3AA5C34371567BD2 in this case):

1

gpg --armor --export 3AA5C34371567BD2

Copy your GPG key, beginning with -----BEGIN PGP PUBLIC KEY BLOCK----- and ending with -----END PGP PUBLIC KEY BLOCK-----.

Add it to your git service.

Setting up git

To instruct git to sign a commit with a specific key, run:

1

git config --local user.signingKey 3AA5C34371567BD2

That’s it.

Workflow

The full process to get up and running with a new git project looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

mkdir project
cd project
git init

git config --local user.email "<EMAIL ADDRESS ASSOCIATED WITH SSH KEY>"
git config --local core.sshCommand "ssh -i <SSH KEY FILE> -F /dev/null"
git config --local user.signingKey <GPG KEY>

git remote add origin git@github.com:example/my-new-project.git
git push -u -f origin main

Notes