How to configure GitHub SSH key authentication

To configure SSH Key autentication with GitHub you need to:

1. Create an SSH key locally on your machine, in case you do not have one.

2. Add the SSH key to your GitHub account.

3. Configure GitHub access. There are two options. Normally only one should be configured.

3a. Configure the SSH agent on your machine to use the SSH key (recommended), or

3b. Configure Glamorous Toolkit with the SSH key, in case the previous option does not work.

NB: In case you are using an SSH key that has a passphrase we strongly recomment to configure the SSH agent, as otherwise when doing the configuration from Glamorous Toolkit , the passphrase is stored in plain text on disk.

1. Creating an SSH key

SSH keys are stored in the .ssh directory in the home directory. In case you do not have a key, you should create one.

Creating an SSH key on Mac or Linux

To create a new SSH key on Mac or Linux run the following command in a terminal using the email from your GitHub account:

ssh-keygen -t ed25519 -C "your_email@example.com"

If you use the default location and name during the generation a new key named id_ed25519 will be create. This will override any existing key with the same name.

You can use the snippet below to view the .ssh directory:

FileLocator home / '.ssh'
  

This is a hidden folder so dependind on your system settings you might not see hidden file.

Creating an SSH key on Windows

On Windows, due to a limitation in libgit, the library used for git operations, it does not work to connect to the existing ssh-agent. As a workaround one can use Pageant, which is part of the PuTTY suite, as an SSH authentication agent.

Note that PuTTY uses a different format for their SSH key files, but they have a keygen program that will convert between the standard format and their format.

You can either use the same command as on Linux or Windows in a Power Shell to create a standard SSH key and covert it afterwards to the format needed by PuTTY. Or directly generate an SSH key using PuTTY by following the instructions from Using PuTTYgen on Windows to generate SSH key pairs.

2. Adding the SSH key to your GitHub account

For this you need to log in into your GitHub accound and the SSH key. Detailed steps for doing this can be found at Adding a new SSH key to your GitHub account.

3a. Adding the key to the ssh-agent

On Mac and Linux you can directly configure the ssh-agent from the operating system with the key. On Windows you should use Pageant.

Configuring the ssh-agent on Mac

First make sure the ssh-agent is started. One way to do this is to execute the following command in a terminal:

eval "$(ssh-agent -s)"

Second, you need to add the key to the ssh-agent, and stores the passphrase in the Keychain. The passphrase, if used, needs to be entered only once; it will be stored in Keychain. You can add the key with one of the following commands, depending on your version of the operating system. In case your key does not have a passphrase you can skip the '--apple-use-keychain' or '-K' parameter. If your key has a passphrase the command will ask you to enter it.

In MacOS Monterey (12.0) and newer versions:

ssh-add --apple-use-keychain ~/.ssh/id_ed25519

In MacOS versions prior to Monterey (12.0)

ssh-add -K ~/.ssh/id_ed25519

The command above needs to be executed after every restart. This can be automated by adding a line with the command in the '.zshrc' file from the home directory. This file contains commands executed when the system starts. You should create the file if it does not already exists; this is a hidden file so dependind on the Finder settings you might not see hidden file.

Configuring the ssh-agent on Linux

First make sure the ssh-agent is started. One way to do this is to execute the following command in a terminal:

eval "$(ssh-agent -s)"

Then you can add the key with one of the following commands:

`ssh-add ~/.ssh/id_ed25519`

If your key has a passphrase, you should run a command from the terminal that uses the SSH key, so that the Desktop Manager asks for the passphrase and stores it. If the passphrase is not stored by the Desktop Manager, git operations that require the SSH key will fail from Glamorous Toolkit.

Configure the Pageant ssh-agent on Windows

Start by installing the PuTTY suite; this comes with Pageant.

Then you can follow the instructions from How To Use Pageant to Streamline SSH Key Authentication with PuTTY to add your SSH key to Pageant.

3b. Configuring Glamorous Toolkit with the SSH key to GitHub

As an alternative to configuring the ssh-agent with your SSH key, you can configure Glamorous Toolkit with the key. This needs to be configured for every new Glamorous Toolkit release. To avoid this by persisting credentials look at How to make GitHub credentials persistent.

NB: if you are using a passphrase, this will store it on disk in plain text, in the directory where Glamorous Toolkit is installed.

To do the configuration run the following snippet:

| credentials store |
credentials := IceSshCredentials new
	host:  #'*';
	username: 'git';
	publicKey: (FileLocator home / '.ssh/id_ed25519.pub') pathString;
	privateKey: (FileLocator home / '.ssh/id_ed25519') pathString;
	"keyPassphrase: 'rsa passphrase';" "Stored in plain text on disk"
	"You can also use 'Clipboard clipboardText asString' to get it from the clipboard"
	yourself.
store := IceCredentialStore current.
store storeSshCredential: credentials forHostname: credentials host.
IceCredentialsProvider useCustomSsh: true.
  

You can also inspect the current store to check that credentials were added:

IceCredentialStore current