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 email@example.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
~/.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!)
$ ssh-keygen -t rsa -b 4096 -C "firstname.lastname@example.org"
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
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):
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
From a command line, use:
sst -T email@example.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.
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
xclip, paste that key into a file named
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.