The Ultimate Manual to GitHub SSH Key Setup

GitHub SSH (Secure Shell) makes it easier to push changes to a user’s GitHub remote repository, meaning you can use SSH with the platform to add an additional layer of security to the system during automated processes.

The biggest benefit here? You don’t have to remember any extra passwords to access the system.

To reiterate, an SSH protocol allows you to connect to remote servers securely without having to manually enter a username and password each time you require access.

But before you can enjoy this benefit, you’ll need a GitHub SSH key. This article will cover SSH keys in more detail, as well as outline the steps to create one and add it to your GitHub account.

What is GitHub?

GitHub is a company that offers a cloud-based Git repository hosting service aimed at simplifying the use of Git for version control and collaboration. One of the biggest advantages of the platform is its user-friendly interface that allows even amateur coders to take full advantage of Git.

Without GitHub, Git would’ve been way more complicated, involving more technical savviness and the use of the command line.

Git is an actively maintained, mature open-source project developed in 2005 by Linus Torvalds, the famous creator of the Linux operating system kernel. Git is an example of a Distributed Version Control System (DVCS). Instead of having a single place for the full version history of the software (something that’s common with obsolete version control systems like CVS and Subversion), Git provides every developer a working copy of the code (also known as a repository) that contains the full history of all changes made.

A large number of software projects rely on Git for version control, including commercial projects, and of course, open-source projects. Within Git, version control allows you to keep track of all changes made to code and give every team member the ability to continue working on the latest version. Using a version control software tool for all code, file, and assets make it easier for multiple team members to collaborate on large projects.

In action, version control helps you:

  • Improves visibility
  • Facilitates easy collaboration between team members around the world
  • Accelerates productivity delivery

What Is a GitHub SSH Key Anyway?

An SSH key is an access credential for the authenticated and encrypted secure shell (SSH) network protocol used for remote communication between machines on an unsecured open network. This key is used for remote file transfer, remote operating system access, and effective network management.

Essentially, the SSH key is like an actual key that only a specific user holds.

You can use an SSH key to access your accounts conveniently and securely. Thanks to the key, you don’t need to remember any long passwords. This gives you the flexibility to choose complicated passwords that no human or bot can guess, without having to remember them yourself!

How an SSH Key Setup Works

When working with a GitHub repository, you have to identify yourself to GitHub by entering your username and password. An SSH key is an alternate method you can identify yourself without using your credentials every time you want in.

GitHub SSH keys come in pairs: a public key and a private key. While the public key is shared with services like GitHub, the private key is solely stored on your computer. You’re granted access only when both keys match. The cryptography behind SSH keys makes sure no one can reverse engineer your private key from the public one, ensuring an unparalleled level of security.

How to Create an SSH Key?

SSH keys are generated through a public key cryptographic algorithm, such as DSA and RSA.

These keys are generated through a mathematical formula that takes two prime numbers and a random seed variable to output the public and the private key at a high level. This whole thing is a one-way formula that makes sure that while the public key can be derived from the private key, the private key cannot be derived from the public key.

To create a GitHub SSH key, you’ll need a key generation tool. The SSH command-line tool suite includes a keygen tool so you can always use that. You have to create the key on your computer first, but if you already have an SSH key, you can skip the steps below. Here’s how to go about this:

Run the following command to check if you have a key:

$ cd ~/.ssh
$ ls

If you see id_rsa.pub, you already have a key pair and don’t need to create a new one.

If you don’t have the key, follow the steps below to create one and copy its contents. Keep in mind that you’ll have to open your computer’s default terminal application for this.

A. Creating an SSH Key on Windows

Here’s a step-by-step tutorial on how to create SSH keys on your Windows devices.

Step 1: Log in to your personal computer as an administrator.

Step 2: Run the following in a prompt command:

ssh-keygen -t ed25519 -C “your_email@example.com”

In case it wasn’t clear, you’ll have to enter your email address. Connecting the key with your email address will help you easily identify the key in the future.

Remember, the ssh-keygen command will only be available if you’ve already installed Git (with Git Bash).

You’ll see a response similar to the following:

C:\Users\ASUS>ssh-keygen -t ed25519 -C “your_email@example.com”
Generating public/private ed25519 key pair.
Enter file in which to save the key (/c/Users/ASUS/.ssh/id_ed25519):

Step 3: Click Enter to accept the default location and file name. If the d.ssh directory is non-existent, the system will create one automatically on your behalf.

Press Enter x2, and then type in a passphrase when prompted. The whole interaction will look something like this:

C:\Users\ASUS>ssh-keygen -t ed25519 -C “your_email@example.com”
Generating public/private ed25519 key pair.
Enter file in which to save the key (/c/Users/ASUS/.ssh/id_ed25519):
Created directory ‘/c/Users/ASUS/.ssh’.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in c/Users/ASUS/.ssh/id_ed25519.
Your public key has been saved in c/Users/ASUS/.ssh/id_ed25519.pub.
The key fingerprint is:
RSA2048:wvaHYeLtY6+DlvV5sFZgDi3RTAe8R2KY23N78qrGqJE your_email@example.com

That’s it! You now have an SSH key for your Windows device.

B. Creating an SSH Key on macOS or Linux

Step 1: Open a terminal on your personal computer and enter the following command:

ssh-keygen -t ed25519 -C “your_email@example.com”

Again, entering your personal email address and associating it with the key will help you identify the key later on. You should see a response similar to the following:

chaiss@C02FP1JWMD6V ~ % ssh-keygen -t ed25519 -C chaiss@email.com
Generating public/private ed25519 key pair.
Enter file in which to save the key (/Users/chaiss/.ssh/id_ed25519):

Step 2: Click Enter to accept the default location and file name. If the d.ssh directory is non-existent, the system will create one automatically on your behalf.

Step 3: Select Enter x2, and then type in a passphrase when prompted. The whole interaction will look something like this:

chaiss@C02FP1JWMD6V ~ % ssh-keygen -t ed25519 -C chaiss@email.com
Generating public/private ed25519 key pair.
Enter file in which to save the key (/Users/chaiss/.ssh/id_ed25519):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /Users/chaiss/.ssh/id_ed25519.
Your public key has been saved in /Users/chaiss/.ssh/id_ed25519.pub.
The key fingerprint is:
RSA2048:gTVWKbn41z6JgBNu3wYjLC4H6oW5bmhaXyaVABwmEtE chaiss@email.com
The key’s randomart image is:
+–[ED25519 256]–+
|==+. +o.. |
|.oE. +o.. |
| . …o |
| .o… |
| oo+S . |
| + ..B = . . |
|.+.+.oo+ * o . |
|o++.o+ . + + |
|B+ o. . . |
+—-[RSA2048]—–+
chaiss@C02FP1JWMD6V ~ %

That’s it! You now have an SSH key for your macOS or Linux device. The random art image is an alternate way to match the keys.

Now that we’ve described a GitHub SSH key setup in detail, let’s revisit a critical aspect.

Your SSH key will have two parts: a private key and a public key. The private key is only meant for private use, and hence, should never be shared with anyone, except maybe your system admin or other trusted people within your organization.

How to Add an SSH Key to Your GitHub Account

In this section, we’ll explain how you can upload your public key to GitHub. Your private key will obviously stay on your local computer, and your only job is to ensure it stays safe from any unauthorized eyes.

Here’s how to add your public SSH key to your GitHub account.

Step 1: Open GitHub, and log in to your account.

Step 2: After selecting your avatar, click on Settings.

Step 3: Choose the SSH and GPG keys on the right-hand side of your screen.

Step 4: Click on the green New SSH key CTA button.

Step 5: Type in a title in the ‘Title‘ field. This can be anything, such as desktop key or laptop key. Once that’s done, paste your public key into the ‘Key‘ field right below the ‘Title‘ field.

Step 6: Click on Add SSH key to confirm details.

And you are done! Simply follow the above steps to add SSH keys to your GitHub account.

You can use SSH keys to authenticate secure connections. Git can use SSH keys instead of traditional password authentication when pushing or pulling to remote repositories as well.

We hope this guide can help you create and start using an SSH key and rest easy when it comes to the security of your systems. Check out our blog to learn more about GitHub.

Every company that uses Google Workspace should be using Nira.
Bryan Wise
Bryan Wise,
CIO of GitLab

Incredible companies use Nira