[Git] How to configure SSH profile for Github account

There are many benefits for using Git with SSH connection.

1. Do not need to type the password every time when pushing the project.
2. Able to configure multiple git accounts in the same machine without using password every time.
3. For Golang projects that reference other Golang private repositories, SSH connection is must thing.

This post will show you how to configure SSH profile for your GitHub account from scratch.

I assume that you did not ever configure the Git on your host. To check it, you can run git config --global --list. The expected output should be empty. If it is not, don’t worry, leave it there for now. We can figure it out later.

If you have configured SSH key, you are safe to skip section 1.

1. Generate SSH Key

Let’s kick off.

1. Open the terminal and cd ~/.ssh.
2. Generate ssh key with ssh-keygen -t rsa -b 4096 -C <comment>. The <comment> can be any string, but it would be better if it is descriptive. For example, ssh-keygen -t rsa -b 4096 -C "oscar-personal-github-key-pair". The output will show as below.

% ssh-keygen -t rsa -b 4096 -C "oscar-personal-github-key-pair"
Generating public/private rsa key pair.
Enter file in which to save the key (/Users/oscarzhou/.ssh/id_rsa): 

I want to give a more descriptive name to the key pair file, such as /Users/oscarzhou/.ssh/oscar-personal-github-id-rsa. Next it will ask to input the passphrase.

Enter file in which to save the key (/Users/oscarzhou/.ssh/id_rsa): /Users/oscarzhou/.ssh/oscar-personal-github-id-rsa
Enter passphrase (empty for no passphrase): 

I want to keep it sample. So I will not enter any passphrase. Just enter to skip it.

Here we go. The ssh key is generated.

Enter passphrase (empty for no passphrase): 
Enter same passphrase again: 
Your identification has been saved in /Users/oscarzhou/.ssh/oscar-personal-github-id-rsa
Your public key has been saved in /Users/oscarzhou/.ssh/oscar-personal-github-id-rsa.pub
The key fingerprint is:
SHA256:V4j9ibKfAzZaS0HAU57vXryD0618Vgnd/Xz1jyEyC0o oscar-personal-github-key-pair
The key's randomart image is:
+---[RSA 4096]----+
|     ..o.        |
|      o..+ .     |
|       o+ o . . o|
|        .. + o .+|
|        S.+ o ..=|
|      E B=o.. ..*|
|     . *.=.*oo +o|
|      o .o=+o.= .|
|          +o+=   |
+----[SHA256]-----+

3. List the directory and you can see that two new files oscar-personal-github-id-rsa and oscar-personal-github-id-rsa.pub are generated.

2. Configure SSH profile

1. Create config file touch ~/.ssh/config with the below content. For github.com, the User must be set as git.

Host oscar-personal-github
        HostName github.com
        User git
        IdentityFile ~/.ssh/oscar-personal-github-id-rsa

2. Test the connection by ssh -T oscar-personal-github. ❗ Remeber this command, I will discuss it later.

% ssh -T oscar-personal-github
Hi oscarzhou! You've successfully authenticated, but GitHub does not provide shell access.

It works. ✌️ So we can trust our SSH profile configuration.

3. Configure Github Account

1. Log in your Github account and head to the Settings page.
2. Navigate to SSH and GPG keys section in the left side bar and then click New SSH key button.
3. Give a key title and keep key type as Authentication Key. Paste the key content generated above into the Key section. You can get the key content by cat ~/.ssh/oscar-personal-github-key-pair.pub. The content is something like

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDITwiXLaD7izkIqzEnudHIS52vXXIEDxlDdkXdN/5UzcpGrmg6k+rtHkIukPbGzyzrucQibkv/fGtNdkAwTCPbT9fXkx4bXE6AOapAIyeuVWdq1gC+Jk5e8NQBzFqyWj73DO16zHq+pP4Cq03jDbU9XRhncPIO6LffYGlq5x989wwNPBMH6VLrVMeIqWRxH3VSrqscM+PZG3uI+pgEGtWoCNe1oHgpIFXpAAPc/y1zWZ27AuNELxDdTWWkrAXbRQsyi7ruLJD3yJcQJCvwFpk8c3GhZ1mvzH1jAaHfgTTHV+l0BFnOynTAqU09tM9aCHoKgBJeax2+dGRE8BI1LvamzBLm8oLd+nG+FMKjvVD3dnJuu89KgKdzXe+Z8+4P+8lIZbt6bNv1zlu9gSA35FxVFNnkHjXMGaZn07UGnYiCr429xmfn4I4CCXZe3vT/9/8zV+TobR5JeJTK2hfZ4+gilnJcxAxC1buPwh5RKpDVHCSWwWIW4+KO14nHGT+nAqm0mZPl4PGAlH5ly7q8VjqN19qysDbigsj80hIE5gKOYHHaRUs25BfnC3AnATT0RtEiF/yqFyPIcPloORsusvcD98SCVgGxgbl/Nd8r4rsehHdz0lN2q4sAG0fVoqJuHndQLz8QcVQVQ3oDqmOCta6CWhkFnThBA6VRZOoNAntAJw== oscar-personal-github-key-pair

4. ❗❗❗ Until now, every setup looks perfect. Next we just need to git clone our private repository with SSH clone string. For example, git clone git@github.com:oscarzhou/private-helloworld.git.

% git clone git@github.com:oscarzhou/private-helloworld.git
Cloning into 'private-helloworld'...
The authenticity of host 'github.com (20.248.137.48)' can't be established.
ED25519 key fingerprint is SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU.
This key is not known by any other names
Are you sure you want to continue connecting (yes/no/[fingerprint])? 

Type yes. Then you will suprisingly see the below failure. 😲

Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
Warning: Permanently added 'github.com' (ED25519) to the list of known hosts.
git@github.com: Permission denied (publickey).
fatal: Could not read from remote repository.

Why does it not work? I will explain the reason, I’m sure it will surprise you again.

4. Final Setup

Subconsciously，we will think that we configured SSH profile for git service and we can use the SSH clone string from Github repository directly.

The thinking is only correct if the name of Host in SSH profile is github.com. For example,

Host github.com
        HostName github.com
        User git
        IdentityFile ~/.ssh/oscar-personal-github-id-rsa

However, in section 2, our configuration is

Host oscar-personal-github
        HostName github.com
        User git
        IdentityFile ~/.ssh/oscar-personal-github-id-rsa

❗❗❗ The trick is that for the command git clone git@github.com:oscarzhou/private-helloworld.git, the git clone will consider the SSH clone string in a format of <SSH Host>:<username>/<repository>.

<SSH Host> here in our configuration should be oscar-personal-github, but git@github.com.

In section two, we tested the SSH profile with ssh -T oscar-personal-github. But if you try it with ssh -T git@github.com, you will see the below output. It is exact same failure that occured before.

% ssh -T git@github.com
git@github.com: Permission denied (publickey).

Therefore, the correct SSH clone string should be oscar-personal-github:oscarzhou/private-helloworld.git. Here we go.

git clone oscar-personal-github:oscarzhou/private-helloworld.git
Cloning into 'private-helloworld'...
remote: Enumerating objects: 86, done.
remote: Counting objects: 100% (86/86), done.
remote: Compressing objects: 100% (78/78), done.
remote: Total 86 (delta 37), reused 17 (delta 2), pack-reused 0
Receiving objects: 100% (86/86), 174.12 KiB | 397.00 KiB/s, done.
Resolving deltas: 100% (37/37), done.

If you got bothered by changing SSH clone string every time, you can update Host field in the SSH profile to github.com. Or please read the next section.

5. A More Common Setup

Even though the SSH profile was successfully configured, it is bit annoying to change default clone string every time.

❗❗❗ Another trick is to configure the Git with below command. This is actually a more common solution.

git config --global url."oscar-personal-github:".insteadOf "https://github.com/"

This command means that everytime when git command is executed, if the url field contains https://github.com/, it will be replaced with oscar-personal-github: (":" must be added).

So from now on, we can copy the HTTPS clone string https://github.com/oscarzhou/private-helloworld.git and run git clone https://github.com/oscarzhou/private-helloworld.git directly. Behind the scene, the clone string will be changed to oscar-personal-github:oscarzhou/private-helloworld.git, which is exactly what we want.