How to Setup a GitHub SSH connection like a PRO.

Discover a more secure and simpler way to push, pull, and clone repositories through GitHub to your local Git repo, or vice versa. The setup is not so simple, which is why many never do it. But once you learn to do it, implement, and use it overtime…you’ll never want to go back to passwords and passphrases.

A better understanding of SSH connections

Hey, like you, for a while, I struggled to wrap my head around what SSH is and how it works. Until several practises, study, and courses; now I finally have a good understanding of the Secure Shell, or SSH for short.

SSH, or Secure Shell, is a way to securely connect and operate a computer over a network, such as the internet. It lets you log in to another computer, execute commands, and transfer files, all while keeping the data safe from outsiders. Think of it as a secure and private conversation between two computers.

It’s a much safer form of secure connection, than passwords. With passwords, hackers have the option of a brute-force hack where they enlist a software that uses probability techniques to guess at your correct password with numerous tries in seconds. With SSH connections, if the hacker doesn’t have access to your private key, there’s no chance or luck of a hack.

How an SSH connection works

You generate an SSH key-pair. Two keys; one is the public key, the other, the private key. These keys are encrypted, meaning they’re not designed to be readable or make much sense, they are hashed. You can also call them hashes or encryption hashes.

The private key stays in your local machine or account while the public key is transferred into the remote machine, server, or account, you want to access.

To authenticate yourself, upon access, the private key is used to decrypt the public key which informs the remote machine, server, or account, that you’re the rightful owner or authorized user.

Okay, enough with the theories, you came here for the how-to guide. Let’s get to it.

Setting up a GitHub SSH connection

GitHub offers multiple forms of secure connection. The default is password-protection. You’re probably using this one, if you’ve not tried to any other means of secure connection.

Today, I’m gonna be sharing how you setup your own SSH connection to GitHub from your local machine. This article may favour Windows users more because I am a Windows user myself, though I’ll endeavour to spot the differences in practise for MacOS users as I spot them.

STEP 1: Check for generated key-pairs in your SSH directory.

Check if you already have keys in your global SSH directory. You may already have keys on your local machine (or PC), check using the command below in your terminal (Git Bash, for Windows PCs).

ls -al ~/.ssh/

STEP 2: Generate an SSH key-pair.

If you find that you do have keys in your SSH directory and you’re certain those keys are for GitHub, then delete them (we’ll create new ones).

If the keys in your SSH directory are not for GitHub, we’ll create new ones for GitHub.

If you do not see any keys at all—FYI, keys look like these id_rsa , id_rsa.pub , id_ed25519 , id_ed25519.pub —not a problem, we’ll create new ones for GitHub.

Before we generate SSH key-pairs, there’re a few things to know and keep in mind.

1. Public keys are keys that are suffixed with ‘.pub’. Private keys are keys that are not suffixed with anything, including ‘.pub’, in other words, private keys have no suffixes (sometimes this may vary, but if it does it’ll be explicitly specified).
2. There are four common SSH key types by algorithm: Digital Signature Algorithm (DSA), Rivest-Shamir-Adleman (RSA), Elliptic curve based algorithms, and Ed25519. GitHub currently accepts three of these, namely; RSA, ECDSA and ED25519.
3. ED25519 is a modern public-key algorithm that offers better security than RSA and is faster in operation. RSA remains the most common and provides the broadest system compatibility.

Having this in mind, we’ll be creating an SSH key-pair using the RSA host key signature algorithm. Let’s begin. Type the command below into your terminal (Git Bash, for Windows PCs).

ssh-keygen -t rsa -b 4096 -C "github your@email_address.com" -N "" -f "/c/Users/YourUsername/.ssh/id_rsa_github"

Let me break it down for you.

• ssh-keygen : This command is used to generate, manage, and convert authentication keys for SSH.
• -t rsa : Specifies the type of key to create, in this case, RSA.
• -b 4096 : Sets the key strength to 4096 bits, which is a good choice for security.
• -C "github your@email_address.com" : Adds a comment to the key. It's useful for identifying the key's purpose or owner. Here, change the email to your GitHub email.
• -N "" : This specifies an empty passphrase for the key, meaning the key will not require a passphrase to use. This is less secure but more convenient (we’ll come back to why I did this later in the article).
• -f "/c/Users/YourUsername/.ssh/id_rsa_github" : Specifies the filename of the key file. This command saves the generated key to a file named id_rsa_github in your .ssh directory. This is useful if you have multiple SSH keys and want to keep them organized. Here, change ‘YourUsername’ to your PC username. We could have used a file path that look like this -f "~/.ssh/id_rsa_github" but may likely throw an error that reads something like "Saving key '~/.ssh/id_rsa_github' failed: No such file or directory”. This is because the Shell does not recognize the file path. This is a common issue when using Git Bash on Windows, due to differences in how Unix-like systems and Windows handle file paths. Therefore you need to use an absolute path, which is the one I recommended in the command.

Running the command above in your terminal will generate two key-pairs and store them in your ‘.ssh’ directory. When you navigate to the ‘.ssh’ directory, you’ll see two keys id_rsa_github.pub (public key), and id_rsa_github (private key).

STEP 3: Transfer your SSH public key to GitHub.

Copy the public key into the clipboard, because we’re about to paste it into our GitHub account to complete the process. Use the command below to do so.

clip < ~/.ssh/id_rsa_github.pub

Now, the public key is in the clipboard, log into your GitHub account, navigate to the Settings page, click the ‘New SSH key’ button, insert/paste the public key into the textarea presented, give it a title, and save by clicking ‘Add SSH key’.

Now, you’ve added your SSH public key into the GitHub servers.

STEP 4: Test your GitHub SSH connection.

Time to test your connection. Run the command below in your terminal.

ssh -i ~/.ssh/id_rsa_github -T git@github.com

This code runs a pseudo-terminal, hence the -T flag, that tests your SSH connection authentication with GitHub servers.

If you followed the steps correctly the command run should return something like this:

Hi (yourGitHubUserName)! You’ve successfully authenticated, but GitHub does not provide shell access.

Hurray! Your GitHub connection is complete, right? Not quite.

Notice that when you run the same SSH connection test without specifying the path—using this flag -i ~/.ssh/id_rsa_github — to your private key, it returns an error that reads like this:

git@github.com: Permission denied (publickey)

This is because the SSH client isn't automatically finding your key because it's not named with one of the default expected filenames (like id_rsa, id_ecdsa, id_ed25519).

To make SSH automatically use your custom-named key—which we named as ‘id_rsa_github’—for GitHub, you have to set up an SSH configuration file to automatically apply specific settings for GitHub.

Doing it like a PRO

So, you’re in the PRO game now. To ensure your SSH connection test works when you simply run the command ssh -T git@github.com , you need to use an SSH config file, as stated in the previous paragraph. Here’s how to do it.

Following from step 4 into…

STEP 5: Setup an SSH Config file.

Create a SSH config file using your favourite text editor (for me, I’ll use vscode). Type the command into the terminal.

code ~/.ssh/config

Add the following configuration to the file:

Host github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_rsa_github
    IdentitiesOnly yes

• Replace ~/.ssh/id_rsa_github with the actual path to your SSH key (which may be the same path as the example if you followed through with everything I said to do, and did not make any personal changes to the filename).
• IdentitiesOnly yes ensures that only the specified key is used for the connection, which can speed up the connection process by not offering other keys.

Save and exit the file.

Now, if you try to test your SSH connection again without specifying the path to the private key. Like so:

ssh -T git@github.com

This should now work and return:

Hi (yourGitHubUserName)! You’ve successfully authenticated, but GitHub does not provide shell access.

Fantastic!

My work here is done (in the voice of Thanos).

And that’s how you setup a GitHub SSH connection like a PRO.

Alternatives to consider

Notice, I didn’t ask you to set a passphrase when we generated an SSH key-pair? That was on purpose. If you’d added a passphrase to your SSH key-pair generation command—by adding content to the -N flag, the process would be slightly different and more bogus, as you’ll have to work with an ssh-agent command, as well as commands such as eval and ssh-add to make it work. Plus, the incessant prompting to input your passphrase into the terminal to decrypt your private key each time you want to SSH connect to GitHub. It gets tiring after a while and is not convenient.

Soon, you’ll realize there’s little to no difference between a passphrase-enabled SSH connection and a password-protected connection to GitHub. That’s why I purposefully did not set a passphrase for the key-pair we generated. This would ensure that your SSH connections to GitHub are always convenient and noninteractive.

Essentially, this means, whenever you use the PC you setup a GitHub SSH connection on to push repos to, pull, and clone repos from GitHub, you’ll not be prompted to input any password or passphrase; the authentication will happen in the background. Which is how I and many other developers and engineers like it. I hope you’ll like it too.

Enjoy.

Thank you for reading.

Stay curious. Stay healthy.

PS. I’ve published this article on LinkedIn and Medium. I’d like to ask you to, please give it a like and share so others may benefit from it too. Thank you again.