GitHub - Configuring SSH credentials

Git
GitHub
SSH
Credentials

Introduction

This page explains how to configure your development environment to authenticate against GitHub using SSH keys. This removes the need of entering the username and password each time we want to push our changes to the remote repositories.

Git configuration

Setting username and email

From Linuxize:

Our commits should appear in the repository history with the same username and email as our GitHub user. In order to do so, we can globally change these like so:

Git username and email global config
$ git config --global user.name "Your GitHub Username"
$ git config --global user.email "YourPrivateGitHubMail@users.noreply.github.com"

where:

  • user.name: use your GitHub username
  • user.email: is the email that GitHub assigns to each user for web-based Git operations, like edits and merges
    • You can find it in your GitHub account -> Settings -> Access/Emails. It appears both in the Primary email address and the Keep my email addresses private sections, and it matches the following format:
    <random-number-sequence>+<Your-GitHub-username>@users.noreply.github.com

These changes are stored in your home directory, inside the ~/.gitconfig file

If you only want to use this configuration for a single repository, execute the same commands without the --global

Git username and email config for single repository
$ git config user.name "Your GitHub Username"
$ git config user.email "YourPrivateGitHubMail@users.noreply.github.com"

In this case, these config changes are stored in the .git/config file within the repository.

GitHub configuration

The full guide can be found here. Make sure to reach the end of the guide (testing your SSH connection) to ensure a correct Git workflow with GitHub

Check for existing SSH keys

If you’re using a shared machine or a cloned VM, it’s always safer to create new SSH keys, but you can check if you already have some by looking at the following path:

~/.ssh
$ ls -la ~/.ssh

GitHub supports the following public keys’ filenames:

  • id_rsa.pub
  • id_ecdsa.pub
  • id_ed25519.pub

Generate a new SSH key

Launch the following command, replacing the email value with the GitHub mail:

SSH key generation, ed25519
$ ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

Just accept everything, and don’t enter a passphrase or you’ll be prompted to enter it each time you git something.

The new SSH key is stored in ~/.ssh/id_ed25519 and ~/.ssh/id_ed25519.pub. The second one is the public key that we’ll share with GitHub.

Add the new SSH key to the ssh-agent

This allows your local ssh client to make use of this key to authenticate against GitHub. Just launch the following commands:

Start the ssh-agent in the background
$ eval "$(ssh-agent -s)"
> Agent pid 59566
Add your SSH private key to the ssh-agent
$ ssh-add ~/.ssh/id_ed25519

Add the SSH public key to your GitHub account

Link to this step

First, we need the content of the public key:

Get the public key value
$ cat ~/.ssh/id_ed25519.pub
  # It will output the content of the file

Then go to your GitHub account via browser to:

  • Settings –> Access –> SSH and GPG keys

Then, click New SSH key or Add SSH key:

  • In “Title”, add a descriptive label for the new key (i.e: “Personal laptop”)
  • Leave the Key type as Authentication Key
  • Paste your public key into the Key field
  • Finish by clicking the Add SSH key button
  • If prompted, confirm access to your account on GitHub

Testing your SSH connection

The last thing to do is test that we can authenticate against github using ssh:

GitHub SSh connection test
$ ssh -T git@github.com
# This attempts to ssh to GitHub and a warning related to an unknown host appears
> The authenticity of host 'github.com (IP ADDRESS)' can\'t be established.
> RSA key fingerprint is SHA256:nThbg6kXUpJWGl7E1IGOCspRomTxdCARLviKw6E5SY8.
> Are you sure you want to continue connecting (yes/no)?

# Just Accept the connection by typing 'yes'

Hi USERNAME! You\'ve successfully authenticated, but GitHub does not
provide shell access.
# This message proves that the connection has been successful!

GitHub repositories checkout

Now, when cloning GitHub repositories, instead of choosing the HTTPS URL, we must use the SSH URL.

Extra: switching existing repositories from HTTPS to SSH

From GitHub:

Most of the times when we clone repositories we instinctively use the first HTTPS URL provided by GitHub, but these are incompatible with SSH authentication; thus, we have to change the remote URLs Git points towards:

Launching this command:

Git: show remote HTTPS URLs
$ git remote -v

# When simply cloning a repo, the default remote paths are named 'origin'
origin  https://github.com/UserName/RepoName.git (fetch)
origin  https://github.com/UserName/RepoName.git (push)
# When cloning a forked repo, the source repository URL appears as 'upstream'
upstream    https://github.com/SourceUserName/RepoName.git (fetch)
upstream    https://github.com/SourceUserName/RepoName.git (push)

will show the location of the remote HTTPS URLs. We must change them by their SSH counterparts:

Git: change remote URLS to SSH ones
# Launch this to change the 'origin'
$ git remote set-url origin git@github.com:UserName/RepoName.git

# Launch this to change the 'upstream'
$ git remote set-url origin git@github.com:SourceUserName/RepoName.git
Git: show remote SSH URLs
$ git remote -v

# When simply cloning a repo, the default remote paths are named 'origin'
origin  git@github.com:UserName/RepoName.git (fetch)
origin  git@github.com:UserName/RepoName.git (push)
# When cloning a forked repo, the source repository URL appears as 'upstream'
upstream    git@github.com:SourceUserName/RepoName.git (fetch)
upstream    git@github.com:SourceUserName/RepoName.git (push)

With this, git will use the SSH keys to authenticate each time any git opeartion is executed in this repository.