Configuring GitHub SSH key access

Posted on: Saturday, Jun 15, 2019

This article shows how to configure your local Linux machine for SSH access to GitHub. If you're using two-factor authentication don't miss step #8.

These instructions apply to Linux machines. While generally the basic instructions apply, you need to keep Googling for details on Windows or Mac GitHub access.

1. Confirm that you cannot currently connect to GitHub with SSH
sst -T git@github.com    

If you get a "successfully authenticated" message, you have GitHub access by SSH key enabled. If you get this message and are still having trouble connecting to GitHub go to step 6.

2. Before you create a new key, see what SSH keys currently exist
    ls -la ~/.ssh 

The ~/.ssh key folder might not exist. It's ok if it doesn't--the next couple of steps will create it if necessary.

If keys are listed, it's assumed you know what their purpose is. If you don't know the purpose of the currently listed keys, don't use the default root key name in Step 3. (Also, find out what those existing keys are for!)

3. Create a new public/private SSH key pair on your local machine
$ ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

You'll be prompted for the key-pair root file name. By default it is id_rsa and that's generally the name you'll want to use. If you use this root name, two files are created in ~/.ssh, id_rsa and id_rsa.pub (and, if ~./ssh doesn't exist, it is created).

If you already had id_rsa* files in ~./ssh, assign a different key-pair root name when asked.

You'll next be prompted for an SSH secure passphrase. Assign a strong passphrase and be sure to record it so you remember it later.

4. Add the new key to the ssh-agent

Start the SSH key agent in the background on your local PC with:

eval "$(ssh-agent -s)"

Then add the key to the agent using the key's root file name (the default name id_rsa is shown here):

ssh-add ~/.ssh/id_rsa 

The example above shows using the default id_rsa default root name. If you customized your root name, but sure to that name here.

At this point, you should have an SSH public/private key pair created on your local machine and registered with the ssh-agent.

5. Add the SSH public key to your GitHub account

Use these instructions to add the SSH key to your GitHub account.

6. Test SSH key access to GitHub

From a command line, use:

sst -T git@github.com

to test SSH access to GitHub. You may be prompted for your SSH key passphrase.

You have GitHub access by SSH key successfully enabled if you get a "successfully authenticated" message with your username,

This error message:

Agent addmitted failure to sign using the key...

most likely means a known problem with some Linux distros has surfaced.

If you receive a "permission denied" message see this link.

7. Cache credentials on your local machine

Despite having SSL key access enabled, GitHub will asking for your credentials each time you connect to GitHub. To cache them on the local machine use these add these two Git configuration options on your local machine:

git config --global credential.helper cache
git config --global credential.helper "cache --timeout=3600"

By default, the cache timeout is 900 seconds (15 minutes). The second line bumps that timeout value to 3600 seconds (60 minutes). Use whatever timeout value you need for this.

8. For users with GitHub two-factor authentication

When you're using two-factor authentication with your GitHub account when Git prompts for a password on your local machine you need to provide a GitHub personal access token, not your GitHub account password.

Follow these instructions to generate a full-access (check every checkbox) personal access token.

Personal access tokens are only displayed once and are forever not visible after that. Make sure to record your personal access right away when it is displayed--GitHub won't ever show it to you again.

With GitHub two-factor authentication enabled, each time Git asks for your password on your local machine, it wants that personal access token--not your GitHub password (despite its confusing wording).

9. Cache your personal access token locally on your machine

This isn't the most secure way to store your GitHub personal access token. Proceed at your own risk!

This optional step needs for you to have the xclip clipboard utility installed. xclip is a Linux utility that lets you easily copy terminal content to the clipboard.

sudo apt-get install xclip

After installing xclip, paste that key into a file named ~/gitpat.txt:

Add a Bash alias named gitpat to quickly put your GitHub personal access token on the clipboard.

alias gitpat='xclip -sel clip < ~/gitpat.txt'

With this alias available, using gitpat on the command line (from any directory) puts your GitHub personal access token on the clipboard for easy pasting when Git asks for it.




Add your comment
You email is never shared with anyone else.

© Copyright 2017 by Roger Pence. All rights reserved.