SSH key setup for Gitlab on Windows

SSH key setup for Gitlab on Windows

On Windows 10, Windows 8.1 and Windows 7

The easiest way to install Git and the SSH client on Windows 8.1 and Windows 7 is Git for Windows. It provides a Bash emulation (Git Bash) used for running Git from the command line and the ssh-keygen command that is useful to create SSH keys as you'll learn below.

GitLab supports RSA, DSA, ECDSA, and ED25519 keys. Their difference lies on the signing algorithm, and some of them have advantages over the others.

ED25519 SSH keys

Following best practices, you should always favor ED25519 SSH keys, since they are more secure and have better performance over the other types.

They were introduced in OpenSSH 6.5, so any modern OS should include the option to create them. If for any reason your OS or the GitLab instance you interact with doesn't support this, you can fallback to RSA.

RSA SSH keys

RSA keys are the most common ones and therefore the most compatible with servers that may have an old OpenSSH version. Use them if the GitLab server doesn't work with ED25519 keys.

The minimum key size is 1024 bits, defaulting to 2048. If you wish to generate a stronger RSA key pair, specify the -b flag with a higher bit value than the default.

The old, default password encoding for SSH private keys is insecure; it's only a single round of an MD5 hash. Since OpenSSH version 6.5, you should use the -o option to ssh-keygen to encode your private key in a new, more secure format.

If you already have an RSA SSH key pair to use with GitLab, consider upgrading it to use the more secure password encryption format by using the following command on the private key:

ssh-keygen -o -f ~/.ssh/id_rsa

Generating a new SSH key pair

Before creating an SSH key pair, make sure to read about the different types of keys to understand their differences.

To create a new SSH key pair:

1. Open a terminal on Linux or macOS, or Git Bash / WSL on Windows.
2. Generate a new ED25519 SSH key pair:

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

   Or, if you want to use RSA:

   ssh-keygen -o -t rsa -b 4096 -C "email@example.com"

   The -C flag adds a comment in the key in case you have multiple of them and want to tell which is which. It is optional.
3. Next, you will be prompted to input a file path to save your SSH key pair to. If you don't already have an SSH key pair and aren't generating a deploy key, use the suggested path by pressing Enter. Using the suggested path will normally allow your SSH client to automatically use the SSH key pair with no additional configuration.
   If you already have an SSH key pair with the suggested file path, you will need to input a new file path and declare what host this SSH key pair will be used for in your ~/.ssh/config file.
4. Once the path is decided, you will be prompted to input a password to secure your new SSH key pair. It's a best practice to use a password, but it's not required and you can skip creating it by pressing Enter twice.
   If, in any case, you want to add or change the password of your SSH key pair, you can use the -p flag:

   ssh-keygen -p -o -f <keyname>

Now, it's time to add the newly created public key to your GitLab account.

Adding an SSH key to your GitLab account

1. Copy your public SSH key to the clipboard by using one of the commands below depending on your Operating System:
   macOS:

   pbcopy < ~/.ssh/id_ed25519.pub

   WSL / GNU/Linux (requires the xclip package):

   xclip -sel clip < ~/.ssh/id_ed25519.pub

   Git Bash on Windows:

   cat ~/.ssh/id_ed25519.pub | clip

   You can also open the key in a graphical editor and copy it from there, but be careful not to accidentally change anything.
   NOTE: Note: If you opted to create an RSA key, the name might differ.
2. Add your public SSH key to your GitLab account by clicking your avatar in the upper right corner and selecting Settings. From there on, navigate to SSH Keys and paste your public key in the "Key" section. If you created the key with a comment, this will appear under "Title". If not, give your key an identifiable title like Work Laptop or Home Workstation, and click Add key.
   NOTE: Note: If you manually copied your public SSH key make sure you copied the entire key starting with ssh-ed25519 (or ssh-rsa) and ending with your email.