Have you ever run across an issue you remember having solved before, but can't remember how to solve it now; then you Google it, find a great article on it, and realize that you wrote it some years back?
That's what this article is. EVERYTIME I have to set up SSH on a new Linux development machine I end up Googling pieces parts here and there and end up cobbling together the solution myself. Then I move on and some time later, have to set up Github SSH on a new Linux machine again. Well that just happened, so I decided to write it all down so that it doesn't trip me up again.
Before I get started with the dry, terminal commands, let me emphasize that the main thing that trips people up is that Github gives you the HTTPS url by default, and you are going to want to use the SSH URL if you want to use Git at the bash prompt.
To begin, fire up the new Linux machine (in this case I'm using Ubuntu Gnome 17.10) and start up a terminal.
Generate your new RSA keypair...
In your Linux Bash prompt, or GitBas on Windows, run ...
$ ssh-keygen -t rsa -b 4096 -C "email@example.com"
- It will default to saving the keypair to the .ssh directory in your home directory as "id_rsa". If that's fine, then just accept the default.
If you already have an id_rsa keypair, then name this one something else. Since this is a ssh key for Gitlab, I called mine "id_rsa_Gitlab". You can also give them project-specific, or account-specific names like, "is_rsa_gfnproject". The convention is that they all start with "id_rsa".
- Enter your passphrase (or leave it blank)
- Enter it again, then the key will be saved.
You will have two files in ~/.ssh/. One of them will be named according to what you specified. This is your private key. The other one has a ".pub" file extension. Open that one in a text editor and copy its contents to your paste buffer.
- Log in to GitHub (or the Git system of your choice)
- Click on your picture in the top-right corner and select "Settings"
- On the left, click on "SSH and GPG keys".
- In the top right corner, click the green [New SSH Key] button.
- Give it a meaningful title, like "Linux Dev Box" and paste the contents of the public key into the "key" field.
- Click the green [Add SSH Key] button.
You should be good to go. Clone a GitHub repo to the local machine like this...
Go to a directory where you want to store your repositories
Execute the following command (modified for your own account and repo)...
$ git clone firstname.lastname@example.org:acctname/reponame.git
You should see the clone procedure run. If it complains about your credentials not being trusted, then have a look at the keys SSH has installed...
Execute the following command
$ ssh-add -l
You should see something like...
4096 SHA256:i2fLkp3x3Dy+V3GpnU5IBWFb0wVZoPBvRsYp4aRWwsL /home/pblanton/.ssh/id_rsa (RSA)
4096 SHA256:i2fLkp3x3Dy+V3GpnU5IBWFb0wVZoPBvRsYp4aRWwsL email@example.com (RSA)
I have of course, shown fake keys for demo purposes.
If you don't see the expected keys, then run this command...
Type in your passphrase (if any), and the SSH client will ingest your keys. Try cloning again, and it should all work. You should be able to Git at the command-line to your heart's content without being prompted for your credentials again.
Time to start writing some shell scripts to automate everything now. Automation is cool!
Normally I am working on a virtual machine that has been especially configured for a client, so creating an ssh public/private keypair, saved as
id_rsa works fine. Today however, I needed to access a Git repository at a client's site, running under a system called "Gerrit" which is a code review system with a Git back-end. This client also has an internal GitHub Enterprise system set up at Github.<clientname>.com, and we also use plain ol' Github.com; That means three different Git systems that I have to access from the same system. I want my Git bash to work in any repository, as it targets any of these systems, transparently. The way to do that is with an ssh config file. After you have created the requisite number of properly named ssh certificates using the instructions above, then you are ready to create your config file as follows...
Navigate to your .ssh directory, open a text editor of your choice and create a file called "config" with no file extension. I'm doing it in Git Bash, so vi...
$ vi config
Edit the file as necessary. Here is an example...
The keys are the Host, and IdentityFile settings as follows...
Host: url that will trigger this identification.
IdentityFile: The SSH Cert to use for this authentication.
The indentation of the IdentityFile line under "Host" is important. Make it one space.
Let's say that I am only using Github, but I have a work account and a personal account on Github. My personal account name is "pblanton" and let's assume I also have a Github account for Gort work. My configuration would look like this...
# SSH Authentication for my personal projects
# SSH Authentication for Gort projects
Now, when you clone a project for your personal work, add "pblanton" to the url. For instance, let's clone WebGoat (firstname.lastname@example.org:WebGoat/WebGoat.git). In this case though if we tweak the url to be
then when we clone it...
Github doesn't care about the extra subdomain, but the Git client will associate it with the credentials specified by the "Host" line that matches "pblanton.Github.com" in the config file, and anytime we push or pull it the correct creds will be used.
Gitlab, BitBucket, et. al.
Since the Git client associates your credentials to the url string found in "Host" you aren't limited to Github. ANY repository that implements Git will work as long as you have a valid "Host" entry that matches the url.
For instance, my GitLab repos can use the credentials in .ssh/id_rsa_lab through the following entry in config...
# SSH Authentication for my personal projects
Since "Gitlab" is unique among the "Host" values in my ssh config file, there is no need to prepend it with "pblanton", but if I had multiple accounts on Gitlab that I used for different purposes, then that would work here too.