Setup SSH keys

Step 1

• Go to your home directory.

Step 2

• Look for .ssh directory. If the .ssh/ directory doesn’t exist, you are either not in the home directory, or you haven’t used ssh before. In the latter case, you need to generate an SSH key pair.

  • You might need to show hidden files if you have it enabled.

Step 3

• See if a file with one of the following formats exists:

  Algorithm	Public key	Private key
  ED25519 (preferred)	id_ed25519.pub	id_ed25519
  ED25519_SK	id_ed25519_sk.pub	id_ed25519_sk
  ECDSA_SK	id_ecdsa_sk.pub	id_ecdsa_sk
  RSA (at least 2048-bit key size)	id_rsa.pub	id_rsa
  DSA (deprecated)	id_dsa.pub	id_dsa
  ECDSA	id_ecdsa.pub	id_ecdsa

Step 1

• Open a terminal.

Step 2

• Run ssh-keygen -t followed by the key type and an optional comment. This comment is included in the .pub file that’s created. You may want to use an email address for the comment.

  For example, for ED25519:

  terminal

  ssh-keygen -t ed25519 -C "<comment>"

  For 2048-bit RSA:

  terminal

  ssh-keygen -t rsa -b 2048 -C "<comment>"

Step 3

• Press Enter. Output similar to the following is displayed:

  terminal

  Generating public/private ed25519 key pair.
  Enter file in which to save the key (/home/user/.ssh/id_ed25519):

Step 4

• Accept the suggested filename and directory, unless you are generating a deploy key or want to save in a specific directory where you store other keys.

  You can also dedicate the SSH key pair to a specific host.

Step 5

• Specify a passphrase:

  terminal

  Enter passphrase (empty for no passphrase):
  Enter same passphrase again:

  A confirmation is displayed, including information about where your files are stored.

Step 1

Copy the contents of your public key file. You can do this manually or use a script. For example, to copy an ED25519 key to the clipboard:

Git Bash on Windows

cat ~/.ssh/id_ed25519.pub | clip

macOS

tr -d '\n' < ~/.ssh/id_ed25519.pub | pbcopy

Linux (requires the xclip package)

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

Replace id_ed25519.pub with your filename. For example, use id_rsa.pub for RSA.

Step 2

Sign in to GitLab.

Step 3

On the left sidebar, select your avatar.

Step 4

Select Edit profile.

Step 5

On the left sidebar, select SSH Keys.

Step 6

Select Add new key.

Step 7

In the Key box, paste the contents of your public key. If you manually copied the key, make sure you copy the entire key, which starts with ssh-rsa, ssh-dss, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521, ssh-ed25519, [email protected], or [email protected], and may end with a comment.

Step 8

In the Title box, type a description, like Work Laptop or Home Workstation.

Optional. Select the Usage type of the key. It can be used either for Authentication or Signing or both. Authentication & Signing is the default value.

Optional. Update Expiration date to modify the default expiration date.

Step 9

Select Add key

Step 1

To ensure you’re connecting to the correct server, check the server’s SSH host keys fingerprint. For:

• For GitLab instance, see gitlab.example.com/help/instance_configuration#ssh-host-keys-fingerprints where gitlab.example.com is the address of the GitLab instance.
• GitLab.com, see the SSH host keys fingerprints  documentation

Step 2

Open a terminal and run this command, assuming we’re connecting to gitlab.forge99.com GitLab instance:

ssh -T [email protected]

Step 3

If this is the first time you connect, you should verify the authenticity of the GitLab host. If you see a message like:

The authenticity of host 'gitlab.forge99.com (167.99.29.106)' can't be established.
ED25519 key fingerprint is SHA256:aJK+GC7NGC3OE67yuuP35ERMpHGJ6inSs9BU+/Tiels.
This key is not known by any other names
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
Warning: Permanently added 'gitlab.forge99.com' (ED25519) to the list of known hosts.

Type yes and press Enter.

Step 4

Run the ssh -T [email protected] command again. You should receive a Welcome to GitLab, @username! message

Sample output: Click here 

If the welcome message doesn’t appear, you can troubleshoot by running ssh in verbose mode:

ssh -Tvvv [email protected]

To view the SSH keys for your account:

Step 1

On the left sidebar, select your avatar.

Step 2

Select Edit profile.

Step 3

On the left sidebar, select SSH Keys.

Your existing SSH keys are listed at the bottom of the page. The information includes:

• The key’s:
  • Name.
  • Public fingerprint.
  • Expiry date.
  • Permitted usage types.
• The time a key was last used.

To permanently delete an SSH key:

Step 1

On the left sidebar, select your avatar.

Step 2

Select Edit profile.

Step 3

On the left sidebar, select SSH Keys.

Step 4

Next to the key you want to delete, select Remove Icon beside of Revoke button.

Step 5

Select Delete to confirm.