Accessing GitHub using SSH keys

Generating a new SSH key

Open a terminal.

Generate your SSH key with the following command.

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

-t The type of key to be generated is specified with the -t option.

-b Specifies the number of bits in the key to create. For RSA keys, the minimum size is 1024 bits and the default is 2048 bits. Generally, 2048 bits is considered sufficient.

-C Provides a new comment. This helps with identifying the key.

Generating public/private rsa key pair.

Next you will be prompted to “Enter a file in which to save the key,” pressing Enter accepts the default file location and name.

Enter a file in which to save the key (/home/you/.ssh/id_rsa): [Press enter]

The next prompt will ask you to enter a passphrase. The passphrase is used to encrypt and decrypt the private key. A key with a passphrase cannot be used until someone enters the correct passphrase. This provides an extra layer of security in the event that someone other than yourself has access to your keys.

Enter passphrase (empty for no passphrase): [Type a passphrase]
Enter same passphrase again: [Type passphrase again]


Adding your SSH key to the ssh-agent

To avoid having to re-enter your passphrase use ssh-agent.

ssh-agent is a program to hold private keys used for public key authentication (RSA, DSA, ECDSA, Ed25519). ssh-agent is usually started in the beginning of an X-session or a login session, and all other windows or programs are started as clients to the ssh-agent program. Through use of environment variables the agent can be located and automatically used for authentication when logging in to other machines using ssh(1).

Start the ssh-agent in the background.

eval "$(ssh-agent -s)"

Add your SSH private key to the ssh-agent. If you created your key with a different name, or if you are adding an existing key that has a different name, replace id_rsa in the command with the name of your private key file.

ssh-add ~/.ssh/id_rsa

This is only maintained as long as the ssh-agent session is active. If you reboot you’ll need to do the above again or consider using something like gnome-keyring.


Adding a new SSH key to your GitHub account

Log into GitHub, go to settings, then SSH and GPG keys, click on New SSH key or Add SSH key. You should be presented with the following form.



In the “Title” field, add a descriptive label for the new key. For example, if you’re using a personal Mac, you might call this key “Personal MacBook Air”.

The next step is to paste the public part of your key pair into the “Key” field.

You can access your SSH key with any text editor to copy its contents. If you used defaults it’ll be located here ~/.ssh/id_rsa.pub. Be cautious when using this method as you might inadvertently include newlines or white spaces. The example below uses a command line program xclip as an alternative method of copying the key to the clipboard that will avoid the potential mishaps of using a text editor.

# Download and install xclip
sudo pacman -S xclip
# For Debian based systems use the following:
sudo apt-get install xclip
# Copy the contents of the id_rsa.pub file to your clipboard
xclip -sel clip < ~/.ssh/id_rsa.pub

Now that the key is saved in the clipboard it’s time to enter it into GitHub.


Testing the SSH connection

Open Terminal.

Enter the following:

# Attempt to SSH into to GitHub
ssh -T git@github.com

You may see a warning like this:

The authenticity of host 'github.com (IP ADDRESS)' can't be established.
RSA key fingerprint is 16:27:ac:a5:76:28:2d:36:63:1b:56:4d:eb:df:a6:48.
Are you sure you want to continue connecting (yes/no)?
or like this:
The authenticity of host 'github.com (IP ADDRESS)' can't be established.
RSA key fingerprint is SHA256:nThbg6kXUpJWGl7E1IGOCspRomTxdCARLviKw6E5SY8.
Are you sure you want to continue connecting (yes/no)?

GitHub’s SSH fingerprints that can be verified here.

Verify that the fingerprint in the message you see matches one of the messages above, then type yes. You should hopefully then see:

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

Troubleshooting

Error: Permission denied (publickey)

If you receive a “permission denied” message, see “Error: Permission denied (publickey)”.


Configuring SSH config

In ~/.ssh/ create a file called config.

Host github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_rsa

Ensure that the IdentityFile is pointing to the correct private key and that the User refers to git and not your GitHub username.

Configure your Git repo

For each Git repo there are 3 pieces of your Git config that are significant, especially for GitHub.

git config user.name "John Doe"
git config user.email "johndoe@example.com"

Git uses a username to associate commits with an identity. The Git username is not the same as your GitHub username.

GitHub uses the email address set in your local Git configuration to associate commits pushed from the command line with your GitHub account.

The last important piece is configuring the remote server.

There are two ways of doing this. By either cloning an existing repository or by setting the git remote command.

Below are examples of both methods using my GitHub account details.

git clone git@github.com:willdotnu/project.git

If you already have a repository you’ll need to configure the git remote for it, like so:

git remote set-url origin git@github.com:willdotnu/project.git

The server name github.com of the SCP like command above is matched to the Host defined in the ssh config. Whenever you now execute a pull/fetch/push request it will use the appropriate SSH key instead of prompting you for a username / password.


Using multiple GitHub accounts

Another benefit of using this method is that it can handle multiple accounts.

# personal
Host github.com-personal
    HostName github.com
    User git
    IdentityFile ~/.ssh/personal-ssh-key

# work
Host github.com-work
    HostName github.com
    User git
    IdentityFile ~/.ssh/work-ssh-key

The git remote commands for each would look similar to the following:

git remote set-url origin git@github.com-personal:user/project.git

git remote set-url origin git@github.com-work:user/project.git


Sources and credits

This tutorial was simply for my own edification. It helped disambiguate some of the things that I was uncertain of.

It’s essentially an amalgamation of the following sources in my own words. A big thank you to Tom from keybits.net for his blog post, it was a huge help in streamlining my workflow.

https://help.github.com/categories/authenticating-to-github/ https://www.keybits.net/post/automatically-use-correct-ssh-key-for-remote-git-repo/ https://git-scm.com/

Returning to freeCodeCamp