Have you heard about SSH keys? They can help us a lot to optimize some repetitive processes when we are updating our remote repositories on GitHub. We will talk about them in this article.
What is SSH?
When downloading a repository from GitHub, we have two protocols at our disposal: 1) HTTPS and 2) SSH. The first option allows us to securely transfer data to our GitHub. When we use this protocol, we need to provide our GitHub username and password every time we want to add new files to our remote repository. This is very secure and works well. However, over time, this process can become a “problem” because the repetitive task of entering our credentials can become tiresome.
But, when we use the second option, SSH, we do not need to provide our username and password with each access. We just need to configure our credentials once and then we can always access our GitHub without providing them, as SSH is specially used to connect to remote servers.
What we need to do is create an SSH key on our local computer and add it to GitHub. This key is like a credential. To understand it better, think of this illustration: when we go to an event, there might be a turnstile or verification system at the event entrance. We can only enter the event if we have a credential, usually a badge with our information. We can say that an SSH key is like this “badge,” which allows us to access GitHub remotely. In this article, we will understand how the creation of this credential works.
Let's first understand the problem that may arise if we do not have an SSH key configured. We will perform the clone of a repository on GitHub. We teach how to create a repository in this article: Creating your first repository on GitHub
When accessing any repository, we see the option to download it. Let's select the SSH option for the clone:
By clicking on this option, we will see the URL of our repository and a button to copy it:
Just an interesting detail: we can already perceive a difference between a repository in SSH and one in HTTPS: the SSH repository starts its address with “[email protected]” while HTTPS starts with “https://github.com”.
Now let's try to execute the git clone command in the Terminal:
git clone [email protected]:anthony-hcode/first-repository.git
When we execute this command, we will see the following response:
Our clone did not work. We see the return of an error message informing us that we do not have the necessary credentials to access the repository. In other words, we were denied permission.
Now, let's start creating and configuring the SSH key to solve this problem. We will divide this process into two steps: 1) create the SSH key on our computer and 2) add this key to GitHub.
Creating an SSH key
In this article, we will execute several commands through the Terminal. If you are using Windows, please use Git Bash. But, if you are using Linux or Mac, you can use the Terminal of these Operating Systems. So, let's start the creation!
Windows
The first command we will execute is ssh-keygen, as we see below:
ssh-keygen -t rsa -b 4096 -C "[email protected]"
Notice that I provided my email in this command. It is important that it is the email registered on your GitHub.
We will need to answer some questions. First, we will be asked where we want to save the file with our key, as we can see below:
By default, this file will be in the user's System folder, inside the .ssh folder, and the file name will be id_rsa.
We can change the name of this file if we want. To do this, we will have to provide the full path to the .ssh folder and the name of the file we want.
The second question will be a password for our key.
We can add any password we want. We even have the option to not add any password to access this key (this is not recommended). After entering the password, just press Enter. It will be requested that we confirm the password. After that, we will see the following result:
Our key was created successfully! We will now create an SSH agent. It is a very useful program that will be responsible for performing our authentication with the remote server, in our case, GitHub. To create it, execute this command:
eval $(ssh-agent -s)
Finally, let's execute the command below:
ssh-add ~/.ssh/id_rsa
We informed the path to the id_rsa file, which was the name we defined for our key. If you changed the name of this file, you will need to inform it when executing this command.
Linux
The process on Linux will be very similar, with a few minor changes. Let's start with the ssh-keygen command:
ssh-keygen -t rsa -b 4096 -C "[email protected]"
After creating it as we explained above, let's create the SSH agent with this command:
eval "$(ssh-agent -s)"
Note that a small difference is that we use quotes in this command, unlike what we see on Windows. Finally, let's add the key from our computer to the agent with this command:
ssh-add ~/.ssh/id_rsa
Mac
Now let's perform the creation on Mac; we are getting good at this process ;).
First, let's execute the ssh-keygen command:
ssh-keygen -t rsa -b 4096 -C "[email protected]"
Let's create our SSH agent:
eval "$(ssh-agent -s)"
And now add the key to the agent:
ssh-add -K ~/.ssh/id_rsa
Notice that in the case of Mac we need to inform the -K parameter for the ssh-add command.
With this, our key is correctly created and configured on our local computer.
Adding SSH key to GitHub
Now that we have our key created, we will add it to github.com. It will be necessary to access the settings page of our GitHub. To do this, click on the top right link on the GitHub site, where our profile picture appears, and then select the “Settings” option:
On the next page, click on the “SSH and GPG keys” option in the panel on the left:
On the next page, we will see the list of SSH keys we already have registered, as well as a button with the option to create a new key:
By clicking this button, we will see this page:
This is the page where we can add an SSH key to GitHub. This key needs a title, which we can choose, and the content of the key itself. To get this content, we will execute one more command in our Terminal, which involves copying the file of the SSH key we just created.
If your computer is Windows, execute the following:
clip < ~/.ssh/id_rsa.pub
If you are using a Mac, execute the command below:
pbcopy < ~/.ssh/id_rsa.pub
But if your computer is Linux, you will need to install the xclip resource to perform the copy process of the file. Execute this command:
sudo apt-get install xclip
After having this tool installed, execute this command:
xclip -sel clip < ~/.ssh/id_rsa.pub
Now that we have the content of the file copied, let's paste it in GitHub and click on “Add SSH key”:
It may be required that we enter our GitHub password. After that, our SSH key will be correctly added. Now, if we try to clone our repository again, with the same command we provided at the beginning of the article, we will see the following result:
The repository cloning process worked correctly! And it will continue to work when executing other git commands, such as git pull or git push.
If you liked this article, don't forget to share it with others. This helps us continue bringing content to our Blog. Until the next article :)