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.

Free VPS Trial
30-day money-back guarantee

Try out your VPS for 30 days. If you're not satisfied, you get your money back.

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
Image: Testing the installation of Git and SSH
We have Git and SSH installed on our system. For example, we are looking for a non-existent command “unknown”.

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"
bash
Note

You can use any email address to generate the SSH key pair. It only serves as a label and doesn’t have to be the same address you use to log into GitHub.

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.

Image: Creating an SSH key pair for GitHub
We have created the SSH key for use with GitHub.
Tip

We use the Ed25519 algorithm for our key pair. In fact, there’s a whole range of al­go­rithms available. We present the en­cryp­tion methods at a glance in a separate article.

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:

Quote

“SSH agent is a program that can keep a user’s private key, so that the private key passphrase only needs to be supplied once. A con­nec­tion to the agent can also be forwarded when logging into a server, allowing SSH commands on the server to use the agent running on the user’s desktop.” / Source: https://www.ssh.com/academy/ssh/keygen#adding-the-key-to-ssh-agent

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.

Image: The GitHub account settings page
Log in to your GitHub account and navigate to the key settings page.
Image: GitHub settings to add an SSH key
Click “New SSH key” under “SSH keys” to open the page to add a new key.

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
Note

Caution: the filename ends in .pub for the “public key”. However, the private key doesn’t end in .priv or the like. Instead, the private key has no ending. Only share the public key with GitHub and other third parties.

Image: content of the public key in the command line
Copy the issued public key and switch back to the GitHub page.
Image: SSH public key copied to GitHub settings page
Paste the copied public key and op­tion­al­ly assign a title. Save the changes by clicking “Add SSH key”.
Image: Overview of added SSH keys in GitHub
The newly added SSH key for GitHub will be shown in the key overview.

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
Image: Positive connection test to GitHub via SSH
The encrypted con­nec­tion with GitHub works.

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”:

Image: Adding the GitHub server to the SSH known hosts
Confirm the addition of the server by typing “yes” and pressing Enter.

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:

Image: Overview page of the cURL repository
Overview of the cURL repos­i­to­ry code / Source: https://github.com/curl/curl
Image: Clone URL of the cURL repository copied
We copy the “clone URL” of the cURL repos­i­to­ry / Source: https://github.com/curl/curl

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
Image: Cloning the cURL repository in the local command line
The cloned cURL repos­i­to­ry is now located in the curl folder.

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
Image: Status of the local cURL repository
Calling up the Git status shows that the status is normal.

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
Image: Result of Git pull and Git push of the local cURL repository
Git pull works. Git push fails because our machine is not au­then­ti­cat­ed.

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
Image: Remotes of the local cURL repository in the command line
The URLs for the Git op­er­a­tions fetch and push are displayed.

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:

Image: Create a new repository on GitHub
We create a new repos­i­to­ry with the name “test”.
Image: Overview of an empty GitHub repository
Our empty GitHub repos­i­to­ry contains in­struc­tions to fill it with code.

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
Image: Changing the push URL and Git push from the local repository
Git push works after changing the push URL.

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:

SSH con­fig­u­ra­tion Path Ex­pla­na­tion
Config folder ~/.ssh/ Contains SSH con­fig­u­ra­tion and key pairs.
Private key ~/.ssh/key-name Private key from a key pair.
Public key ~/.ssh/key-name.pub Public key from a key pair.
Config file ~/.ssh/config SSH con­fig­u­ra­tion file.
Known hosts ~/.ssh/known_hosts List of hosts connected in the past.

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
Image: Inserting the GitHub configuration into SSH config file
Paste the con­fig­u­ra­tion block and press Ctrl + X to write the changes and close the editor.
Image: Writing the modified SSH config file
Confirm the name of the file by pressing Enter.
Image: Confirming the changes to the SSH config file
Confirm writing the changes by pressing Enter.

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:

Setting Ex­pla­na­tion Example
Host Can contain any number of names. github.com github
HostName Host name of the remote system running SSH. An IP address can also be used. github.com
User Git user on the remote system. Must be applied exactly. git
Iden­ti­ty­File Absolute path to the private key. Adjust this if you use multiple keys. ~/.ssh/github_id_ed25519
Iden­ti­tiesOn­ly Specifies that access for this host must be by key only. yes

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.

Go to Main Menu