How to use an SSH key with GitHub

Using an SSH key with GitHub enables pass­word­less access to Git repos­i­to­ries. Instead of iden­ti­fy­ing a user by username and password, your machine is au­then­ti­cat­ed via the SSH key.

What is an SSH key?

The Secure Shell (SSH) is the standard tool for encrypted access to remote systems. SSH allows you to log into a server from your home machine. Git uses SSH as a transfer protocol and allows read and write access to remote repos­i­to­ries.

An encrypted con­nec­tion is used to enable au­then­ti­ca­tion of the machine and to ensure that the trans­mit­ted data cannot be falsified. Without this, it would be possible for unknown parties to make arbitrary changes to repos­i­to­ries.

GitHub via SSH uses asym­met­ric en­cryp­tion as a cryp­to­graph­ic method. First, a pair of private and public keys is created. This is also referred to as a “public / private key pair”. The private key remains on the user’s own computer. The public key is shared with third parties, e.g., GitHub.

If you use an SSH key to access GitHub repos­i­to­ries, you don’t need to enter a password. In general, pass­word­less logins are con­sid­ered more secure because a password can be picked up on by key­log­gers or trojans. Instead of a person knowing the password, a machine is au­then­ti­cat­ed on which the private key is stored.

Using GitHub via SSH is extremely con­ve­nient. Once it’s set up, the SSH key allows permanent access to GitHub without further in­ter­ven­tion. Other protocols and services also benefit from SSH keys for an encrypted network con­nec­tion. In addition to Git with SSH, the secure SFTP protocol can be used to exchange files with servers without the need for further con­fig­u­ra­tion.

Con­nect­ing to Git repos­i­to­ries is usually done from the command line. If an SSH key has been set up, a push to a custom repos­i­to­ry can be performed without any problems:

cd ./folder-with-git-repo/
git push

Besides the command line ap­pli­ca­tion, GUI ap­pli­ca­tions also benefit from an es­tab­lished SSH key. Modern FTP programs support the SSH File Transfer Protocol (SFTP). This is based on SSH and uses existing SSH keys.

How do you use SSH keys with GitHub?

To access your GitHub account with an SSH key, you deposit the public key with GitHub. The private key remains on your own computer. Your machine is au­then­ti­cat­ed to GitHub by comparing the key data. This allows write access to your own repos­i­to­ries. This method also works with al­ter­na­tives to GitHub like Gitlab or Bitbucket.

As con­ve­nient as SSH keys are, you must exercise caution when using them. Do not share your private key under any cir­cum­stances. The private key may allow another party to im­per­son­ate you. A third party could log into a server or modify code in repos­i­to­ries in your name.

Re­quire­ments for using GitHub with an SSH key

We’re assuming here that you work in a Linux-like en­vi­ron­ment. This includes Linux/Unix, macOS, as well as Windows with WSL2 installed. In addition, the following con­di­tions must be met:

• Git has been installed
• SSH has been installed
• A GitHub account has been created

First, let’s check if the local re­quire­ments are met. With the following command, we test if Git and SSH are installed. Unless you get a “git not found” or “ssh not found” error message, both are present:

which git ssh

Close

Fur­ther­more, we create the .ssh directory in the user folder if it doesn’t already exist:

mkdir -vp ~/.ssh/

We’ll explain below how to create and register an SSH key to use GitHub. Once this step is complete, we’ll show you how to deposit the public SSH key with GitHub and explain how to access Git repos­i­to­ries using SSH:

1. Create SSH key pair on your own system
2. Deposit public SSH key with GitHub
3. Access GitHub repos­i­to­ry with SSH key

Create and register an SSH key on your own system

As a first step, we’ll create a public / private SSH key pair on our local system. Copy the commands used for this in the exact same order and run them from your command line.

We follow the official doc­u­men­ta­tion from GitHub here. The procedure changes from time to time so, to fix SSH errors, it can’t hurt to look there.

First, we start the SSH key generator to create a public / private key pair for GitHub. We use the ssh keygen command, which is present by default as part of the OpenSSH in­stal­la­tion on the system:

We call up ssh keygen from the command line and are presented with three options:

• Option -f followed by path and name of the new key
• Option -t followed by the name of the algorithm, in this case ed25519
• Option -C followed by email address as a comment

ssh-keygen -f "$HOME/.ssh/github_id_ed25519" -t ed25519 -C "your_email@example.com"

The SSH keygen command asks us to specify a “passphrase” for the private key. Unlike a password, a passphrase can contain spaces. The passphrase should be several words long and is then just as easy to remember as it is difficult to guess. Include some digits or special char­ac­ters for increased security. Type the passphrase and press “Enter”. Repeat the process to complete the creation of the SSH key pair.

Close

Before we can use our freshly generated SSH key with GitHub, we perform one more step. This is optional, but highly rec­om­mend­ed. We add the private key to the “SSH agent”. This is a back­ground program that runs on the local system. Run the following command from the command line and enter the passphrase when asked:

• Windows / Linux

ssh-add ~/.ssh/github_id_ed25519

• macOS to 11 Big Sur

ssh-add -K ~/.ssh/github_id_ed25519

• macOS from 12 Monterey

ssh-add --apple-use-keychain ~/.ssh/github_id_ed25519

The SSH agent has access to added private keys and allows you to use them to connect without entering the passphrase every time. But the SSH agent can do even more:

Deposit SSH key with GitHub

We have created an SSH key pair on our local system. This provides one half of the encrypted com­mu­ni­ca­tion when using GitHub with SSH. The remaining step is to deposit the public SSH key with GitHub.

Close

Close

Now we need the contents of the public key. Switch to your local command line and enter the following command:

cat ~/.ssh/github_id_ed25519.pub

Close

Close

Close

Access GitHub repos­i­to­ry with an SSH key

We have generated the keys locally and deposited the public SSH key with GitHub. First, let’s test if the con­nec­tion works using the following command:

ssh -T git@github.com

Close

If this is your first time con­nect­ing to GitHub from this machine, you’ll also be prompted to add the server to the “known hosts”:

Close

When accessing GitHub repos­i­to­ries, we dis­tin­guish between read and write access. Public repos­i­to­ries can be read by anyone. No au­then­ti­ca­tion, i.e., no SSH key, is required.

To download a repos­i­to­ry as a local copy, use the Git clone command. We’ll demon­strate this using the repos­i­to­ry of the popular network tool cURL as an example. We visit the GitHub page of the public cURL repos­i­to­ry and copy the clone URL:

Close

Close

Equipped with the clone URL, we switch back to the local command line. We create a sample folder repo on the desktop and switch to that. We then clone the cURL repos­i­to­ry by calling up Git clone with the clone URL:

cd ~/Desktop/
mkdir -p repo && cd repo
git clone https://github.com/curl/curl.git

Close

We switch to the cURL repos­i­to­ry folder and use the Git status command to display the status of the repos­i­to­ry:

cd ~/Desktop/repo/curl/
git status

Close

The Git pull command, which brings a repos­i­to­ry up to date, also requires read-only access. We run Git pull in the repos­i­to­ry folder. In principle, this works even if there are likely no changes yet:

git pull

Now, we try to write to the GitHub repos­i­to­ry using the Git push command:

git push

Close

What’s going on here? The clone URL used to clone the public cURL repos­i­to­ry starts with HTTPS. Ac­cord­ing­ly, for our local clone, an HTTPS URL is stored as “Origin”. We check the origin with the Git show command:

git remote -v show

Close

For read access, an HTTPS URL is suf­fi­cient, but an SSH key is required to write to GitHub repos­i­to­ries. This is because user au­then­ti­ca­tion via username / password is no longer supported on GitHub as of August 2021.

We use a trick to test Git push anyway. First, we create on GitHub our own empty repos­i­to­ry:

Close

Close

Following the in­struc­tions on GitHub, we change the push URL of the local cURL clone on our system to use our empty GitHub repos­i­to­ry as origin. Fur­ther­more, we set the branch to “main”. We then execute the Git push. The operation completes suc­cess­ful­ly and uses our pre­vi­ous­ly created SSH key to au­then­ti­cate us to GitHub.

git remote set-url origin git@github.com:<user>/test.git</user>
git branch -M main
git push -u origin main

Close

Use multiple SSH keys for different GitHub accounts

It’s possible to use only one SSH key for different GitHub or other accounts without any problems. Remember: we can share the public key without hes­i­ta­tion.

Tech­ni­cal­ly, it’s quite possible to use your own SSH keys for different services and sites. There are two possible methods:

1. Call up SSH command with pa­ra­me­ters
2. Create SSH config file

SSH commands with pa­ra­me­ters may turn out to be very long, which is why we’re not showing this approach here. In general, it’s more con­ve­nient to work with an SSH config file. This requires a little more effort to configure your own system, but it only needs to be done once. Here’s an overview of the folders and files involved in SSH con­fig­u­ra­tion:

First, we create the SSH config file. We create the file, adjust the user rights and open it in the command line editor:

touch ~/.ssh/config
chmod 600 ~/.ssh/config
nano ~/.ssh/config

Then, copy the following block into the editor and follow the screen­shots to save the file:

# Github
Host github github.com
    HostName github.com
    User git
    IdentityFile "~/.ssh/github_id_ed25519"
    IdentitiesOnly yes

Close

Close

Close

After inserting the GitHub con­fig­u­ra­tion block, an SSH con­nec­tion can be es­tab­lished by spec­i­fy­ing the specified host ab­bre­vi­a­tion github:

ssh -T github

Follow the schema shown to add con­fig­u­ra­tion blocks for ad­di­tion­al services or accounts to the SSH config file. Here’s an overview of the pa­ra­me­ters that are used:

One final tip. If you create SSH con­fig­u­ra­tions for multiple hosts with their own keys, you should add a block of settings for unlisted hosts at the end of the file:

# For all hosts
Host *
IdentitiesOnly no
IgnoreUnknown UseKeychain, AddKeysToAgent
UseKeychain yes
AddKeysToAgent yes

This allows access without an SSH key to un­spec­i­fied hosts. You can connect to a host via SSH command with your username and enter the password when con­nect­ing:

ssh user@host

Without the line “Iden­ti­tiesOn­ly no” in the final con­fig­u­ra­tion, SSH tries all keys in ~./ssh/ one after the other to connect to the server. If there’s no matching key, the error “Too many au­then­ti­ca­tion failures” occurs.