Using an SSH key with GitHub enables pass­word­less access to Git re­pos­it­or­ies. Instead of identi­fy­ing a user by username and password, your machine is au­then­tic­ated via the SSH key.

Free VPS Trial
Try a virtual server risk-free for 30 days

Try out your VPS for 30 days. If you're not satisfied, we'll fully reimburse you.

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 re­pos­it­or­ies.

An encrypted con­nec­tion is used to enable au­then­tic­a­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 re­pos­it­or­ies.

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 re­pos­it­or­ies, you don’t need to enter a password. In general, pass­word­less logins are con­sidered 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­tic­ated on which the private key is stored.

Using GitHub via SSH is extremely con­veni­ent. 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­ur­a­tion.

Con­nect­ing to Git re­pos­it­or­ies is usually done from the command line. If an SSH key has been set up, a push to a custom re­pos­it­ory can be performed without any problems:

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

Besides the command line ap­plic­a­tion, GUI ap­plic­a­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­tic­ated to GitHub by comparing the key data. This allows write access to your own re­pos­it­or­ies. This method also works with al­tern­at­ives to GitHub like Gitlab or Bitbucket.

As con­veni­ent 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 re­pos­it­or­ies 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­vir­on­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 re­pos­it­or­ies using SSH:

  1. Create SSH key pair on your own system
  2. Deposit public SSH key with GitHub
  3. Access GitHub re­pos­it­ory 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­ment­a­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­stall­a­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 'pass­phrase' for the private key. Unlike a password, a pass­phrase can contain spaces. The pass­phrase 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 pass­phrase 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­gorithms 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 re­com­men­ded. 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 pass­phrase 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 pass­phrase 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 pass­phrase 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­nic­a­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­ally 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 re­pos­it­ory 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 re­pos­it­or­ies, we dis­tin­guish between read and write access. Public re­pos­it­or­ies can be read by anyone. No au­then­tic­a­tion, i.e., no SSH key, is required.

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

Image: Overview page of the cURL repository
Overview of the cURL re­pos­it­ory code / Source: https://github.com/curl/curl
Image: Clone URL of the cURL repository copied
We copy the 'clone URL' of the cURL re­pos­it­ory / 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 re­pos­it­ory 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 re­pos­it­ory is now located in the curl folder.

We switch to the cURL re­pos­it­ory folder and use the Git status command to display the status of the re­pos­it­ory:

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 re­pos­it­ory up to date, also requires read-only access. We run Git pull in the re­pos­it­ory folder. In principle, this works even if there are likely no changes yet:

git pull

Now, we try to write to the GitHub re­pos­it­ory 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­tic­ated.

What’s going on here? The clone URL used to clone the public cURL re­pos­it­ory starts with HTTPS. Ac­cord­ingly, 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 re­pos­it­or­ies. This is because user au­then­tic­a­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 re­pos­it­ory:

Image: Create a new repository on GitHub
We create a new re­pos­it­ory with the name 'test'.
Image: Overview of an empty GitHub repository
Our empty GitHub re­pos­it­ory 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 re­pos­it­ory as origin. Fur­ther­more, we set the branch to 'main'. We then execute the Git push. The operation completes suc­cess­fully and uses our pre­vi­ously created SSH key to au­then­tic­ate 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­it­a­tion.

Tech­nic­ally, 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 para­met­ers
  2. Create SSH config file

SSH commands with para­met­ers may turn out to be very long, which is why we’re not showing this approach here. In general, it’s more con­veni­ent 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­ur­a­tion:

SSH con­fig­ur­a­tion Path Ex­plan­a­tion
Config folder ~/.ssh/ Contains SSH con­fig­ur­a­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­ur­a­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­ur­a­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­ur­a­tion block, an SSH con­nec­tion can be es­tab­lished by spe­cify­ing the specified host ab­bre­vi­ation github:

ssh -T github

Follow the schema shown to add con­fig­ur­a­tion blocks for ad­di­tion­al services or accounts to the SSH config file. Here’s an overview of the para­met­ers that are used:

Setting Ex­plan­a­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­tity­File Absolute path to the private key. Adjust this if you use multiple keys. ~/.ssh/github_id_ed25519
Iden­tit­iesOnly Specifies that access for this host must be by key only. yes

One final tip. If you create SSH con­fig­ur­a­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­spe­cified 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­tit­iesOnly no' in the final con­fig­ur­a­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­tic­a­tion failures' occurs.

Go to Main Menu