SSH key

The Secure Shell Protocol (SSH) is used for securely accessing and managing remote systems over a network. It can be used to access remote repositories on GitHub, GitLab and Bitbucket. SSH keys can be used to authenticate to those repository hosting services.

When only one SSH key is needed to configure, the section that covers Managing multiple SSH keys can be ignored.

Generate a new SSH key

Create a new SSH key using the ssh-keygen tool.

Adding the SSH key

The previous command generated two files (unless another file name or path was specified at the Generate a new SSH key section):

~/.ssh/id_ed25519 (private key)
~/.ssh/id_ed25519.pub (public key)

Copy entire contents of the ~/.ssh/id_ed25519.pub file. The following command demonstrates how to copy a file to the clipboard:

cat ~/.ssh/id_ed25519.pub | wl-copy

In this example the output of the cat command got redirected to wl-copy; a utility part of wl-clipboard. Add the key (that should be inside the clipboard now) to a {GitHub, Bitbucket, GitLab} account.

Adding the private SSH key to the ssh-agent

Choose one of the following options to add an SSH key to the ssh-agent.

Option 1: use ssh-add manually

Add the private SSH key previously generated to the ssh-agent by executing the following command:

ssh-add ~/.ssh/id_ed25519

This process can be automated by having this command in the Bash or Zsh configuration file.

Option 2 (preferred): use Keychain

The Keychain tool has better tooling for adding SSH keys. Refer to Add an SSH key to Keychain for how to add an SSH key to Keychain.

Managing multiple SSH keys

When two or more SSH keys are used, more steps are required to let SSH know which key to use when.

Add both the SSH keys to the ssh-agent

Use one of the options explained in Adding the private SSH key to the ssh-agent for each SSH key. Verify that all SSH keys are loaded by executing the command:

ssh-add -l

If Keychain is used reference List loaded SSH keys.

Create or modify the SSH configuration

To tell Git which SSH key to use when interacting with the remote repository, we need to configure the ~/.ssh/config file. Make a host entry with the following settings for each key:

Host github.com
    HostName github.com
    User user_name
    IdentityFile ~/.ssh/id_ed25519-personal
    IdentitiesOnly yes

Host bitbucket.com
    HostName bitbucket.org
    User user_name
    IdentityFile ~/.ssh/id_ed25519-work
    IdentitiesOnly yes

Make the Host name the same has the HostName. When those are the same there is no need to update any existing remotes because the URL stays the same.

When using multiple Git identities, also follow Git identities.

Update the existing remotes

When the Host name has the same name as the HostName, this section can be skipped.

When the Host name is not the same has the HostName need, modify the remotes to specify which host should be used: Instead of the default domain name for the host, the Host name specified in the ~/.ssh/config file must be used.

git remote set-url {remote_name} git@{Host}:{workspace}/{repository}.git

Example for this repository when Host is named github instead of github.com:

git remote set-url origin git@github:th7mo/second-brain.git

Make sure that the local gitconfig has the correct user.name and user.email for authentication.