Using SSH Keys with Github

Content:

In late 2021, Github permanently changed the way users authenticate with the platform.

It’s no longer possible to interact with Github repositories using your password. Instead, there are two authentication options to choose from.

The first, using Personal Access Tokens (PATs), is useful for shorter-term access – perhaps you’re using a device you wouldn’t usually use.

The second, using SSH, is a great option if you usually interact with Github on the machine you’re trying to connect with. Once an SSH key is set up, you can use the PC for as long as the key is attached to your Github account.

This guide will show you how to configure your system for Github SSH access.

Generating an SSH Key

To generate an SSH key, we’ll be using ssh-keygen. Run the following command, replacing the email address with the email address used by your Github account.

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

ed25519 is a variant of the Edwards-curve Digital Signature Algorithm. This is a modern and commonly-used algorithm. If your system does not support ed25519, you can use the older RSA algorithm instead.

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

You’ll be prompted to enter a file name to use for the new key.

Generating public/private ed25519 key pair.
Enter file in which to save the key (/home/user/.ssh/id_ed25519):

You can use the default name, or specify your own if you prefer. It might be helpful to name the file ‘github’ or similar, so you’ll know later on what the key is used for.

You’ll then be prompted to enter a passphrase.

Enter passphrase (empty for no passphrase):

The passphrase acts like a password for the SSH key. The passphrase can be cached, so it doesn’t need to be entered every time. Alternatively, it’s possible to leave the passphrase blank.

Consider your use case, and the likelihood of your system being compromised, before proceeding without a passphrase.

Once the key is created, you’ll need to add the key to the ssh-agent. ssh-agent keeps track of SSH keys on the system. We can do this using ssh-add.

ssh-add /home/user/.ssh/id_ed25519

Replace the path with the file path entered earlier on.

The SSH key is now set up and ready on the system. It now needs to be added to Github.

Adding the Key to Github

To add the key to Github, we need to read the contents of the public key file generated earlier. We can do this using cat.

cat /home/user/.ssh/id_ed25519.pub

Again, replace the file name with the one used earlier, but be sure to keep the .pub file extension. The .pub file contains the public part of the key.

You should see an output similar to the one below.

ssh-ed25519 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBA5Oe8l1tt72A6XX user@example.com

In a web browser, navigate to the ‘SSH and GPG keys‘ section of your Github account.

Click ‘New SSH Key’ and copy/paste the output from the cat command. Be sure to copy the entire output, including the email address.

Click ‘Add SSH Key’ to add the key to your account.

Testing the Key

Github have provided a simple way to test that the key is working correctly.

Once the key is saved you your account, try to connect to Github over SSH. Don’t worry, Github don’t provide public shell access. You won’t be able to mess with their systems.

ssh -T git@github.com

If successful, you should get the response

Hi {Github username}! You've successfully authenticated, but GitHub does not provide shell access.

This means your key is configured correctly.

Configuring Repositories to Use the Key

To interact with repositories using the SSH key, it’s important to note that the remote URL is different to the one previously used for password-based authentication.

While the previous remote URL would have look something like

https://github.com/username/reponame.git

The new URL used for SSH-based connections looks like

git@github.com:username/reponame.git

Replace the username and reponame sections as appropriate, but leave git@github.com.

It’s important to keep this in mind, especially if you’re working with existing repositories already set up on your system.

To alter the remote location of an existing repository, you can run

git remote set-url branchname git@github.com:username/reponame.git

Replace the relevant fields with data for your repository.

If you fail to do this, the system will continue to prompt for your account password – only to then fail to sync changes.

macOS: