Chapter 2. Git & GitHub Initial Settings

GitHub SSH Setup

GitHub SSH Setup
Tag:

To establish an SSH connection, you need an SSH key pair (a private key and a public key) and upload the public key to the GitHub platform.

One of the benefits of SSH connection is the easiness of connecting to the GitHub repository. If you skip setting a passphrase or use ssh-agent, you don't need to type a passphrase every time you connect with a GitHub repository.

There are several approaches in SSH settings. In this topic, we'll explain the most simple one. In the next topic, we'll explain more advanced settings using ssh-agent and customizing the SSH key file path. If you want to pursue the advanced settings, you can skip this page and go to the next page.

In the approach that we'll explain on this page, there are four key steps:

  1. Generate an SSH key pair
  2. Copy the public key
  3. Upload the public key to GitHub
  4. Test connection with GitHub

1 Generate an SSH key pair

The first step in SSH setup is to generate a new SSH key pair. To generate it, run the command below.

ssh-keygen -t ed25519 -C "your email address"

File path

When running the command, you’ll be asked to enter the file in which to save the key. You can specify a file path or you can just hit the enter key to skip. If you skip the setting, the key pair will be created in the default path.

Passphrase

When running the command, you’ll be asked to set a passphrase. This passphrase gives another layer of security. If you don't want to type a passphrase every time you connect to GitHub, you can skip setting a passphrase although the security level decreases.

To set a passphrase, type your passphrase twice. Save the passphrase as the passphrase is used when you establish ssh connection.

When the command is executed, the files of the public and private keys are generated under the .ssh directory under your user home directory. As it is a hidden directory, you need to change the settings to show the hidden directory. For Mac OS, press the shift + command + . keys.

GitHub-SSH-Setup

Command Options

-t option is to set security type. rsa has mainly been used; however, GitHub recommends ed25519 now for better security. If you are using a legacy system that doesn't support the Ed25519 algorithm, you can use rsa. The command to generate an SSH key is the one below.

ssh-keygen -t rsa -b 4096 -C “your email address”

Check this link GitHub – Generating a new SSH key for more details.

-C option is to overwrite a comment in the key. As the default comment is username@hostname, it is good to overwrite to avoid disclosing your hostname. Typically, an email address is used for the comment.

2 Copy the public key

To add the public key to GitHub in the next step, you need to copy it first.

cat command

Show public key content by running the cat command.

cat file_path

Copy the displayed public key and go to the next step.

pbcopy or clip command

Alternatively, you can directly copy the content of the file without displaying the file content by using the pbcopy command for Mac,

pbcopy < file_path

or the clip command for Windows.

clip < file_path

For Linux, a similar command may not be available by default unless you install it.

3 Upload the public key to GitHub

You need to add the copied public key to the GitHub account setting page by conducting the following actions.

— Go to the GitHub website

— Click your icon

— Press the Settings button

— Select SSH and GPG keys on the left side bar

— Press New SSH key button

— Set Title and paste the public key

4 Test connection with GitHub

You can check if you can connect with GitHub using the ssh command with the -T option.

ssh -T git@github.com

You'll see a message confirming that you’ve been successfully authenticated.

Practice

Objective:
Set up an SSH connection to GitHub

In this practice example, we use bloovee as a username and bloovee@example.com as an email address. You need to change them to your own username and email.

Note: The file path shown in the command line response is an example based on Mac OS.

1. Generate an SSH key pair

Run the ssh-keygen command

Command Line - INPUT
ssh-keygen -t ed25519 -C "bloovee@example.com"

After running the command, you’ll be asked to indicate the file path to save the file.

Command Line - RESPONSE
Generating public/private ed25519 key pair.
Enter file in which to save the key (/Users/bloovee/.ssh/id_ed25519):

The default SSH key path

The default SSH key file paths are slightly different by OS as the OS user home directory paths are different.

Windows: /C/Users/bloovee/.ssh/id_ed25519

Linux: /home/bloovee/.ssh/id_ed25519

To create an SSH key pair in the default file path, hit the enter key. You'll be asked for a passphrase.

Command Line - INTERACTIVE
Enter passphrase (empty for no passphrase):
Enter same passphrase again:

To create the key pair without a passphrase, hit the enter key two times. A key pair is saved under the file path displayed. You'll see the following response in your command line.

Command Line - RESPONSE
Your identification has been saved in /Users/bloovee/.ssh/id_ed25519
Your public key has been saved in /Users/bloovee/.ssh/id_ed25519.pub
The key fingerprint is:
SHA256:xxxxxxxxxxxxxx bloovee@example.com
The key's randomart image is:
+--[ED25519 256]--+
|         ..E     |
|          o      |
|    o + .. .     |
|     & = +.   . o|
|    + X.S..    =.|
         :
+----[SHA256]-----+

You can confirm that the two files are generated in the .ssh directory under your home directory. The .ssh directory is a hidden directory. If you cannot see it, you need to make hidden directories and files visible. For Mac, press the shift + command + . keys.

2. Copy the public key

cat command

Show public key content by running the cat command.

Command Line - INPUT
cat ~/.ssh/id_ed25519.pub
Command Line - RESPONSE
ssh-ed25519 xxxxxxxxxxxxxxxxxxxxxx bloovee@example.com

Copy the displayed public key and go to the next step.

pbcopy or clip command

Alternatively, you can directly copy the content of the file without displaying it by using the pbcopy command for Mac, or the clip command for Mac

For Mac:
Command Line - INPUT
pbcopy < ~/.ssh/id_ed25519.pub
For Windows:
clip < ~/.ssh/id_ed25519.pub

3. Upload the public key to GitHub

Go to the GitHub website, click your icon, and press the Settings button.

GitHub-SSH-Setup

Select the SSH and GPG keys on the left sidebar and press the New SSH key button.

GitHub-SSH-Setup

Fill title name (any name) in the Title field and paste the public key information in the Key field.

GitHub-SSH-Setup

You'll see that the public key is registered.

GitHub-SSH-Setup

4. Test connection with GitHub

Run the ssh command with the GitHub URL.

Command Line - INPUT
ssh -T git@github.com

You may get the following message if you are connecting to GitHub first time.

Command Line - INTERACTIVE
The authenticity of host 'github.com (20.27.177.113)' 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 and hit the enter key

If the test connection is successful, you'll see the message below.

Command Line - RESPONSE
Hi bloovee! You've successfully authenticated, but GitHub does not provide shell access.

Now, you are ready to connect to GitHub with SSH.

To establish an SSH connection, you need an SSH key pair (a private key and a public key) and upload the public key to the GitHub platform.

One of the benefits of SSH connection is the easiness of connecting to the GitHub repository. If you skip setting a passphrase or use ssh-agent, you don't need to type a passphrase every time you connect with a GitHub repository.

There are several approaches in SSH settings. In this topic, we'll explain the most simple one. In the next topic, we'll explain more advanced settings using ssh-agent and customizing the SSH key file path. If you want to pursue the advanced settings, you can skip this page and go to the next page.

In the approach that we'll explain on this page, there are four key steps:

  1. Generate an SSH key pair
  2. Copy the public key
  3. Upload the public key to GitHub
  4. Test connection with GitHub

1 Generate an SSH key pair

The first step in SSH setup is to generate a new SSH key pair. To generate it, run the command below.

ssh-keygen -t ed25519 -C "your email address"

File path

When running the command, you’ll be asked to enter the file in which to save the key. You can specify a file path or you can just hit the enter key to skip. If you skip the setting, the key pair will be created in the default path.

Passphrase

When running the command, you’ll be asked to set a passphrase. This passphrase gives another layer of security. If you don't want to type a passphrase every time you connect to GitHub, you can skip setting a passphrase although the security level decreases.

To set a passphrase, type your passphrase twice. Save the passphrase as the passphrase is used when you establish ssh connection.

When the command is executed, the files of the public and private keys are generated under the .ssh directory under your user home directory. As it is a hidden directory, you need to change the settings to show the hidden directory. For Mac OS, press the shift + command + . keys.

GitHub-SSH-Setup

Command Options

-t option is to set security type. rsa has mainly been used; however, GitHub recommends ed25519 now for better security. If you are using a legacy system that doesn't support the Ed25519 algorithm, you can use rsa. The command to generate an SSH key is the one below.

ssh-keygen -t rsa -b 4096 -C “your email address”

Check this link GitHub – Generating a new SSH key for more details.

-C option is to overwrite a comment in the key. As the default comment is username@hostname, it is good to overwrite to avoid disclosing your hostname. Typically, an email address is used for the comment.

2 Copy the public key

To add the public key to GitHub in the next step, you need to copy it first.

cat command

Show public key content by running the cat command.

cat file_path

Copy the displayed public key and go to the next step.

pbcopy or clip command

Alternatively, you can directly copy the content of the file without displaying the file content by using the pbcopy command for Mac,

pbcopy < file_path

or the clip command for Windows.

clip < file_path

For Linux, a similar command may not be available by default unless you install it.

3 Upload the public key to GitHub

You need to add the copied public key to the GitHub account setting page by conducting the following actions.

— Go to the GitHub website

— Click your icon

— Press the Settings button

— Select SSH and GPG keys on the left side bar

— Press New SSH key button

— Set Title and paste the public key

4 Test connection with GitHub

You can check if you can connect with GitHub using the ssh command with the -T option.

ssh -T git@github.com

You'll see a message confirming that you’ve been successfully authenticated.

Practice

Objective:
Set up an SSH connection to GitHub

In this practice example, we use bloovee as a username and bloovee@example.com as an email address. You need to change them to your own username and email.

Note: The file path shown in the command line response is an example based on Mac OS.

1. Generate an SSH key pair

Run the ssh-keygen command

Command Line - INPUT
ssh-keygen -t ed25519 -C "bloovee@example.com"

After running the command, you’ll be asked to indicate the file path to save the file.

Command Line - RESPONSE
Generating public/private ed25519 key pair.
Enter file in which to save the key (/Users/bloovee/.ssh/id_ed25519):

The default SSH key path

The default SSH key file paths are slightly different by OS as the OS user home directory paths are different.

Windows: /C/Users/bloovee/.ssh/id_ed25519

Linux: /home/bloovee/.ssh/id_ed25519

To create an SSH key pair in the default file path, hit the enter key. You'll be asked for a passphrase.

Command Line - INTERACTIVE
Enter passphrase (empty for no passphrase):
Enter same passphrase again:

To create the key pair without a passphrase, hit the enter key two times. A key pair is saved under the file path displayed. You'll see the following response in your command line.

Command Line - RESPONSE
Your identification has been saved in /Users/bloovee/.ssh/id_ed25519
Your public key has been saved in /Users/bloovee/.ssh/id_ed25519.pub
The key fingerprint is:
SHA256:xxxxxxxxxxxxxx bloovee@example.com
The key's randomart image is:
+--[ED25519 256]--+
|         ..E     |
|          o      |
|    o + .. .     |
|     & = +.   . o|
|    + X.S..    =.|
         :
+----[SHA256]-----+

You can confirm that the two files are generated in the .ssh directory under your home directory. The .ssh directory is a hidden directory. If you cannot see it, you need to make hidden directories and files visible. For Mac, press the shift + command + . keys.

2. Copy the public key

cat command

Show public key content by running the cat command.

Command Line - INPUT
cat ~/.ssh/id_ed25519.pub
Command Line - RESPONSE
ssh-ed25519 xxxxxxxxxxxxxxxxxxxxxx bloovee@example.com

Copy the displayed public key and go to the next step.

pbcopy or clip command

Alternatively, you can directly copy the content of the file without displaying it by using the pbcopy command for Mac, or the clip command for Mac

For Mac:
Command Line - INPUT
pbcopy < ~/.ssh/id_ed25519.pub
For Windows:
clip < ~/.ssh/id_ed25519.pub

3. Upload the public key to GitHub

Go to the GitHub website, click your icon, and press the Settings button.

GitHub-SSH-Setup

Select the SSH and GPG keys on the left sidebar and press the New SSH key button.

GitHub-SSH-Setup

Fill title name (any name) in the Title field and paste the public key information in the Key field.

GitHub-SSH-Setup

You'll see that the public key is registered.

GitHub-SSH-Setup

4. Test connection with GitHub

Run the ssh command with the GitHub URL.

Command Line - INPUT
ssh -T git@github.com

You may get the following message if you are connecting to GitHub first time.

Command Line - INTERACTIVE
The authenticity of host 'github.com (20.27.177.113)' 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 and hit the enter key

If the test connection is successful, you'll see the message below.

Command Line - RESPONSE
Hi bloovee! You've successfully authenticated, but GitHub does not provide shell access.

Now, you are ready to connect to GitHub with SSH.

Tag: