How to setup the Git SSH keys

When working with Git using the command line, the most common way to handle authentication is through the use of SSH keys.

Most GUI-based clients like GitHub Desktop will handle this for you, but sometimes you need the command line, and so it’s very useful to have a SSH key setup in place.

Also, sometimes you’ll need an SSH key to do useful things like pulling a repository on a remote server.

If those remote servers are yours, don’t stop at client keys. I built a free SSH hardening checklist that covers sshd_config and the usual lock-down steps.

For connecting to servers (not just Git), host verification, and ~/.ssh/config aliases, see SSH for developers.

Keys on your computer

SSH keys are stored in the ~/.ssh folder.

You can have more than one key in there, because SSH keys are used for things other than Git.

You can list all your SSH keys by typing

ls -al ~/.ssh

If you have existing keys you’ll notice that they sit in pairs, one file and another similarly named ending with .pub:

The .pub file contains the public key, while the other file contains the private key which should never be shared anywhere.

You should never share the private key anywhere. If you lose the private key, you’ll have to regenerate a new private/public key pair, as the authentication cannot be successfully completed without the private key part.

Generating a new key

You generate a new SSH key using the command ssh-keygen, which is available on all macOS, Linux and modern Windows computers with the Linux subsystem or the Git for Windows package.

This is the command to use. It creates an Ed25519 key, the type GitHub’s docs use today (when I first wrote this post the standard was RSA):

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

The last part, which in this example is filled with an email address, is a comment. You can enter any email you want, it does not have to be your GitHub account or it can even be a random string. It can be useful to know who generated the key if there is potential for ambiguity.

The key generation program will ask you where you want to save the key. If this is the first key, you are suggested to use id_ed25519 as the filename, but you’d better choose a file name that remembers you the service you are generating it for, like github_ed25519.

You can optionally add a password. I highly recommend setting the password. On macOS you can store it in the Keychain so you don’t have to repeat it every time: run ssh-add --apple-use-keychain ~/.ssh/github_ed25519 once (on macOS versions before Monterey the flag was -K), and add UseKeychain yes under the host entry in your ~/.ssh/config.

If you are on an old system that does not support Ed25519, use RSA with a 4096 bit key:

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

Add the key to GitHub

I show the process for GitHub, but it’s the same kind of process that every Git platform uses, with small differences.

In the GitHub settings, under the “Access” section of the sidebar, you’ll find the “SSH and GPG keys” menu.

That page lists the keys already tied to your account. On mine there are 3, one I use locally on my mac, and 2 I use on the remote servers to pull the website code.

Press “New SSH key” to add a new one. The form asks for a title and the key.

You set the title to be something meaningful, which you’ll remember 2 years+ from now.

The key is the one you generated before.

You can open the .pub file of the key, copy its content and paste it in this box.

You can do so using any CLI command like cat id_ed25519.pub and you copy/paste the whole key code with the mouse.

Once you save that string to GitHub (or any other service, as the concept is the same for everyone), your Git client will have the credentials it needs to communicate with the remove server, and you should be good to go!

Using multiple keys

It’s recommended to use a different SSH key for every service you intend to use.

This makes it very easy to invalidate a key on a specific service without having to change it on all the services you use if you decide to renew it, either because compromised/publicly exposed or for some other reason.

Want me to talk about your product? You can sponsor this site.