How to Set SSH Key in GitLab: A Step-by-Step Guide

In the world of software development, secure and efficient access to your repositories is crucial. SSH keys provide a robust method for authenticating and establishing a secure connection between your local machine and remote GitLab repositories. This step-by-step guide will walk you through the process of setting up SSH keys in GitLab, ensuring that your workflow remains both seamless and secure.

Key Takeaways

  • Understanding the importance of SSH keys for secure authentication in GitLab.
  • Learning how to generate a new SSH key pair on different operating systems.
  • Steps to add your SSH key to the SSH agent for streamlined access.
  • How to copy and add your SSH public key to your GitLab account.
  • Best practices for managing and updating SSH keys to maintain security.

Understanding SSH Keys and Their Importance

What are SSH Keys?

In order to communicate over SSH (Secure Shell), you must have an SSH key pair. Each SSH key pair has a public and a private key.

  • Public Key – Can be used to encrypt data in such a way so only the holder of the corresponding private key can decrypt it.
  • Private Key – Can be used as proof of identity, and is used to authenticate a user’s connection to the server.

The public key can be distributed freely, while the private key should be protected and kept confidential. It is not possible to reveal confidential data by uploading your public key. When you need to copy or upload your SSH public key, make sure you do not accidentally copy or upload your private key instead.

Why Use SSH Keys for GitLab?

Aside from the comfort provided by not having to submit your username and password for each action you take, SSH keys are generally much more secure than a username and password. Humans aren’t very good at remembering a large number of secure passwords so they tend to reuse passwords over multiple sites, resulting in many vulnerabilities. No system connected to the internet is truly secure, but with an SSH key you greatly reduce the chance of human error giving away your access privileges.

Using SSH keys greatly enhances the security of your remote connections and provides a cryptographic method to prove your identity.

Prerequisites for Setting Up SSH Keys in GitLab

Required Tools and Software

Before you start setting up SSH keys for GitLab, ensure you have the necessary tools and software installed. You will need Git installed on your system. You can download it from the official Git website and follow the installation instructions for your operating system.

Checking for Existing SSH Keys

Before generating a new SSH key pair, it’s a good idea to check if you already have one. Open your terminal or command prompt and run the following command:

ls -al ~/.ssh

This command will list the files in your .ssh directory, if it exists. Look for files named id_rsa and (or similar). If these files are present, you already have an SSH key pair. If not, you’ll need to generate a new one.

Note: Having multiple SSH keys is possible, but it requires additional configuration to specify which key to use for GitLab.

Generating a New SSH Key Pair

person generating SSH key on computer

Using Command Prompt on Windows

To generate a new SSH key pair on Windows, follow these steps:

  1. Open Command Prompt.
  2. Run the command: ssh-keygen -t ed25519 -C "". This will generate an ED25519 key pair, which is recommended for its security.
  3. Follow the prompts to save the key in the default location and set an optional passphrase.

Using Terminal on macOS and Linux

Generating an SSH key pair on macOS and Linux is straightforward:

  1. Open Terminal.
  2. Run the command: ssh-keygen -t rsa -b 2048 -C "" for an RSA key or ssh-keygen -t ed25519 -C "" for an ED25519 key.
  3. Follow the prompts to save the key and set an optional passphrase.

Setting a Passphrase

When generating your SSH key pair, you will be prompted to set a passphrase. Setting a passphrase adds an extra layer of security to your SSH key. If your private key is ever compromised, the passphrase will help protect your GitLab account.

It’s highly recommended to use a strong, unique passphrase and store it securely. This is especially important if you are using GitLab Ultimate, which may contain sensitive and critical data.

Adding Your SSH Key to the SSH Agent

Starting the SSH Agent

To start the SSH agent, open your terminal and run the following command:

eval $(ssh-agent -s)

This command initializes the SSH agent and outputs the process ID. Make sure the agent is running before proceeding to the next step.

Adding the SSH Key to the Agent

Once the SSH agent is running, you need to add your SSH key. Use the following command to add your key:

ssh-add ~/.ssh/your_key

Replace your_key with the actual name of your private key file. If your key is stored in a different location, provide the full path to the key file.

It’s crucial to ensure your private key has the correct permissions. Run chmod 400 ~/.ssh/your_key to set the appropriate permissions.

After adding the key, you can verify it by running:

ssh-add -l

This command lists all the keys currently managed by the SSH agent. If your key appears in the list, it has been successfully added.

Copying the SSH Public Key

Locating Your Public Key File

First, you need to locate your public key file. Typically, this file is found in the ~/.ssh directory and is named something like or You can navigate to this directory using the following command:

cd ~/.ssh

Once you’re in the .ssh directory, you can list the files to confirm the presence of your public key file:


Look for a file with a .pub extension, as this is your public key.

Using Commands to Copy the Key

After locating your public key file, the next step is to copy its contents. You can do this manually by opening the file in a text editor and copying the text, or you can use a command to copy it directly to your clipboard. Here are the commands for different operating systems:

  • macOS:

    pbcopy < ~/.ssh/
  • Linux (requires the xclip package):

    xclip -sel clip < ~/.ssh/
  • Git Bash on Windows:

    cat ~/.ssh/ | clip

Note: Make sure you copy the entire key, starting from ssh-rsa and ending at your email address or hostname.

Pro Tip: Double-check that you are copying the public key and not the private key. The private key should remain secure and never be shared.

Adding the SSH Key to Your GitLab Account

Navigating to GitLab Settings

To add your SSH key to GitLab, start by logging into your GitLab account at GitLab. Once logged in, click on your avatar in the top right corner and select Settings from the drop-down menu. In the settings menu, find and click on SSH Keys.

Pasting the SSH Key

After navigating to the SSH Keys section, you will see a field labeled Key. Paste your copied SSH public key into this field. Optionally, you can add a descriptive title in the Title field to help you identify the key later. This is especially useful if you manage multiple keys.

Verifying the Key Addition

Once you have pasted your SSH key and added a title, click on the Add Key button. You should now see your SSH key listed along with its fingerprint and creation date. Make sure to verify that the key has been added correctly by checking its details. If you encounter any issues, double-check that you have copied the key correctly and that it is in the proper format.

Adding your SSH key to GitLab is a crucial step in securing your repositories, especially if you are using GitLab Premium. Ensure that your key is kept secure and updated regularly to maintain the integrity of your access.

Configuring SSH for Custom Key Locations

When working with SSH keys, you might need to configure your SSH client to point to a custom directory where your private key is stored. This is especially useful if you did not save your SSH key pair in the default directory.

Modifying the SSH Config File

To configure SSH to use a custom key location, you need to modify the SSH config file. This file is typically located at ~/.ssh/config. If it doesn’t exist, you can create it. Here’s how you can do it:

  1. Open a terminal and run the following command to start the SSH agent:
    eval $(ssh-agent -s)
  2. Add your private key to the SSH agent using:
    ssh-add <path_to_private_key>
  3. Open (or create) the SSH config file in a text editor:
    nano ~/.ssh/config
  4. Add the following configuration to specify the custom key location:
      PreferredAuthentications publickey
      IdentityFile <path_to_private_key>

Specifying the Key Location

In the SSH config file, you can specify different key locations for different hosts. This is particularly useful if you are working with multiple GitLab instances or other SSH servers. Here’s an example configuration:

  PreferredAuthentications publickey
  IdentityFile ~/.ssh/gitlab_com_rsa

# Private GitLab instance
  PreferredAuthentications publickey
  IdentityFile ~/.ssh/company_com_rsa

Pro Tip: Always ensure that your SSH config file has the correct permissions. You can set the appropriate permissions using the command chmod 600 ~/.ssh/config.

By following these steps, you can easily configure your SSH client to use keys stored in custom locations, making your workflow more flexible and secure.

Testing Your SSH Connection to GitLab

After setting up your SSH key, it’s crucial to verify that the connection to your GitLab instance is working correctly. This ensures that you can securely and seamlessly interact with your repositories without any issues.

Best Practices for Managing SSH Keys

Regularly Updating Your SSH Keys

To maintain the security of your SSH communications, it’s crucial to regularly update your SSH keys. This practice helps in reducing the risk of keys falling into the wrong hands. As an admin, you may want to set up expiration policies, so that new keys need to be generated periodically, and old keys will no longer be valid. This greatly reduces the risk of the keys falling into the wrong hands.

Keeping Your Private Key Secure

Your private key is the most sensitive part of your SSH key pair. Ensure it is stored securely and never shared. Do not backup your SSH keys as the only thing that does is create a vulnerability. Instead, if you ever find yourself on a different computer, simply generate a new SSH key pair and upload the public key to GitLab. If a computer is lost, simply delete the public key from your GitLab account and all is well.

Remember, creating new keys and revoking old ones is a lot less painful than dealing with the fallout of a leaked SSH key pair.

Common Issues and How to Resolve Them

When working with SSH keys in GitLab, you might encounter several common issues. This section will help you troubleshoot and resolve these problems effectively.


Setting up SSH keys in GitLab is an essential step for securing your interactions with remote repositories. By following this guide, you should now have a clear understanding of how to generate an SSH key pair, add it to your GitLab account, and configure your system to use it. This not only enhances security but also streamlines your workflow by eliminating the need for repetitive password prompts. Remember, keeping your private key secure is crucial, so store it in a safe location and avoid sharing it. With your SSH keys properly configured, you can now focus on your development tasks with greater peace of mind.

Frequently Asked Questions

What are SSH Keys?

SSH keys are a pair of cryptographic keys used to authenticate a user or device in a secure manner. They are commonly used in various applications like GitLab to provide secure access to repositories.

Why use SSH Keys for GitLab?

Using SSH keys for GitLab enhances security by eliminating the need to enter a username and password each time you interact with your repositories. It also helps in automating scripts and CI/CD pipelines.

How do I generate an SSH key pair on Windows?

To generate an SSH key pair on Windows, open the command prompt and enter the command `ssh-keygen`. Follow the prompts to save the key and set a passphrase if desired.

How do I add my SSH key to the SSH agent?

To add your SSH key to the SSH agent, start the agent using `eval $(ssh-agent -s)` and then add your key using `ssh-add ~/.ssh/your_key_file`.

How do I add my SSH key to my GitLab account?

Log in to your GitLab account, navigate to Settings, click on SSH Keys, and paste your public key into the Key box. Finally, click the Add Key button to save it.

What should I do if my SSH key is not recognized?

If your SSH key is not recognized, ensure that the public key has been correctly added to your GitLab account. Also, verify that the SSH agent is running and the key has been added to it.

How can I test my SSH connection to GitLab?

You can test your SSH connection to GitLab by running the command `ssh -T`. If everything is set up correctly, you should see a success message.

What are the best practices for managing SSH keys?

Best practices for managing SSH keys include regularly updating your keys, keeping your private key secure, and using a strong passphrase to protect your key.

You may also like...