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

Secure Shell (SSH) keys provide a secure way to access your GitLab repositories without repeatedly entering your username and password. This guide will walk you through the process of creating, adding, and managing SSH keys in GitLab, ensuring a secure and efficient workflow for your projects.

Key Takeaways

  • Learn the basics and importance of SSH keys in GitLab.
  • Understand the prerequisites and tools required for generating SSH keys.
  • Step-by-step instructions for generating SSH keys on Windows, macOS, and Linux.
  • How to add and verify your SSH key in GitLab.
  • Best practices for managing and securing your SSH keys.

Understanding SSH Keys and Their Importance

What is an SSH Key?

SSH uses two keys, a public key and a private key.

  • The public key can be distributed.
  • The private key should be protected.

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 in GitLab?

Use SSH keys when you want to:

  • Check out internal submodules.
  • Download private packages using your package manager. For example, Bundler.
  • Deploy your application to your own server or, for example, Heroku.
  • Execute SSH commands from the build environment to a remote server.
  • Rsync files from the build environment to a remote server.

If anything of the above rings a bell, then you most likely need an SSH key.

Security Benefits of SSH Keys

The SSH stands for Secure Shell or Secure Socket Shell used for managing the networks, operating systems and configurations and also authenticates to the GitLab server without using username and password each time. You can set the SSH keys to provide a reliable connection between the computer and GitLab. Before generating ssh keygen, you need to have Git installed in your system.

SSH keys offer a robust method of securing your connections and operations, ensuring that your data remains protected and confidential.

Prerequisites for Creating an SSH Key in GitLab

Required Tools and Software

Before you start creating an SSH key for GitLab, ensure you have the necessary tools and software. You will need the OpenSSH client, which is pre-installed on most GNU/Linux distributions, macOS, and Windows 10. Additionally, make sure you have Git installed on your system.

Setting Up Your Environment

Setting up your environment is crucial for a smooth SSH key creation process. Open a terminal or command prompt on your computer. This will be your primary interface for generating and managing SSH keys.

Checking for Existing SSH Keys

Before generating a new SSH key, it’s a good idea to check if you already have one. You can do this by navigating to your .ssh directory and listing the files:

cd ~/.ssh

If you see files like id_rsa and, you already have an SSH key pair. You can either use the existing key or create a new one if needed.

Note: If you are using GitLab Ultimate, you may have additional features and settings available for SSH key management.

Generating an SSH Key on Windows

Creating an SSH key on Windows is a straightforward process. This section will guide you through the necessary steps to generate an SSH key using Command Prompt, save the key file, and set a passphrase for added security.

Generating an SSH Key on macOS and Linux

Creating an SSH key on macOS and Linux is a straightforward process that involves using the Terminal. This section will guide you through the steps to generate an SSH key, specify the key file location, and set a passphrase for added security.

Adding Your SSH Key to GitLab

Accessing GitLab Settings

To add your SSH key to GitLab, first, log in to your GitLab account at GitLab. Once logged in, click on the Settings option located in the top right drop-down menu, which appears when you select your profile icon.

Navigating to the SSH Keys Section

In the settings menu, find and click on the SSH Keys section. This is where you will add your new SSH key.

Pasting Your SSH Key

  1. Open the file containing your public SSH key. This file typically ends with .pub.
  2. Copy the entire contents of the file.
  3. Paste the copied SSH key into the provided Key box in GitLab.
  4. Click the Add Key button to save your SSH key.

Note: If you are using GitLab Premium, you may have additional options for managing your SSH keys, such as setting expiration dates or restricting key usage to specific IP addresses.

Verifying Your SSH Key in GitLab

Checking the SSH Key Fingerprint

After generating the key, try to sign in to the remote server to accept the fingerprint:


It is a good practice to check the private server’s own public key to make sure you are not being targeted by a man-in-the-middle attack. If anything suspicious happens, you notice it because the job fails (the SSH connection fails when the public keys don’t match).

Testing the SSH Connection

Verify that your SSH key was added correctly by testing the connection to your GitLab instance. Use the following command, replacing with your GitLab instance’s hostname:

ssh -T

If everything is set up correctly, you should see a message confirming your successful authentication.

Troubleshooting Common Issues

If you encounter issues, here are some common troubleshooting steps:

  1. Check for existing SSH keys: Ensure that the correct SSH key is being used.
  2. Verify the SSH config file: Make sure your SSH config file points to the correct key.
  3. Restart the SSH agent: Sometimes, restarting the SSH agent can resolve connection issues.
eval $(ssh-agent -s)
ssh-add ~/.ssh/id_rsa

If you continue to experience issues, consult the GitLab documentation or seek help from your system administrator.

Configuring SSH to Use a Custom Directory

Changing the Default SSH Directory

If you did not save your SSH key pair in the default directory, you need to configure your SSH client to point to the directory where the private key is stored. This ensures that your SSH operations can locate the correct key files.

  1. Open a terminal and run the following command to start the SSH agent:
    eval $(ssh-agent -s)
  2. Add your private SSH key to the agent:
    ssh-add <directory to private SSH key>

Updating SSH Config File

To make these settings persistent, save them in the ~/.ssh/config file. This file allows you to specify different SSH keys for different hosts.

For example:

  PreferredAuthentications publickey
  IdentityFile ~/.ssh/gitlab_com_rsa

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

Verifying the Configuration

After updating your SSH configuration, it’s important to verify that everything is set up correctly. You can do this by attempting to connect to your GitLab instance using SSH.

  1. Test the SSH connection:
    ssh -T
  2. If everything is configured correctly, you should see a success message.

Tip: If you encounter any issues, double-check the file paths and permissions of your SSH keys.

Using Your SSH Key with Git Operations

person using laptop with SSH key and GitLab logo

Once you have your SSH key set up and added to GitLab, you can start using it for various Git operations. This section will guide you through the essential tasks you can perform using your SSH key.

Cloning a Repository with SSH

To clone a repository using SSH, you need to copy the SSH URL of the repository from GitLab. Open your terminal and run the following command:

git clone

This command will create a local copy of the repository on your machine. Make sure your SSH key is loaded into your SSH agent to avoid authentication issues.

Fetching and Pulling Changes

Fetching and pulling changes from a remote repository are common tasks in Git. To fetch changes, use the following command:

git fetch origin

To pull changes and merge them into your local branch, use:

git pull origin branch-name

These commands will ensure your local repository is up-to-date with the remote repository.

Pushing Changes to GitLab

After making changes to your local repository, you can push them to GitLab using SSH. First, stage your changes:

git add .

Then commit your changes:

git commit -m "Your commit message"

Finally, push your changes to the remote repository:

git push origin branch-name

This will upload your changes to GitLab, making them available to other collaborators.

Using SSH keys for Git operations not only enhances security but also streamlines the process by eliminating the need for repetitive username and password entries.

Managing Multiple SSH Keys

Managing multiple SSH keys can be essential for developers who work on various projects or use different accounts. This section will guide you through creating, configuring, and switching between multiple SSH keys efficiently.

Creating Multiple SSH Keys

To create multiple SSH keys, you need to generate a new key pair for each account or project. Use the following command to generate a new SSH key:

ssh-keygen -t rsa -b 4096 -C ""

Make sure to specify a unique file name for each key pair to avoid overwriting existing keys.

Configuring SSH for Multiple Keys

Once you have generated multiple SSH keys, you need to configure SSH to use the correct key for each account or project. This can be done by editing the SSH config file located at ~/.ssh/config. Add the following entries to the config file:

Host gitlab-account1
  User git
  IdentityFile ~/.ssh/id_rsa_account1

Host gitlab-account2
  User git
  IdentityFile ~/.ssh/id_rsa_account2

This configuration tells SSH which key to use when connecting to different GitLab accounts.

Switching Between SSH Keys

Switching between SSH keys is straightforward once you have configured your SSH config file. Simply use the appropriate host alias when performing Git operations. For example, to clone a repository using the first account, use the following command:

git clone git@gitlab-account1:username/repo.git

To clone a repository using the second account, use:

git clone git@gitlab-account2:username/repo.git

Pro Tip: Always ensure that your SSH keys are stored securely and backed up to prevent any loss of access to your repositories.

By following this guide, you can efficiently manage multiple SSH keys and streamline your workflow across different GitLab accounts and projects.

Best Practices for SSH Key Management

Managing your SSH keys effectively is crucial for maintaining the security and efficiency of your development workflow. Here are some best practices to follow:

Regularly Updating Your SSH Keys

To ensure the highest level of security, it’s important to update your SSH keys regularly. This helps mitigate the risk of unauthorized access due to compromised keys. Make it a habit to rotate your keys every few months.

Using Strong Passphrases

A strong passphrase adds an extra layer of security to your SSH keys. Avoid using simple or easily guessable passphrases. Instead, opt for a combination of letters, numbers, and special characters. This makes it significantly harder for attackers to gain access.

Backing Up Your SSH Keys

Losing your SSH keys can be a major setback. Always keep a secure backup of your keys in a safe location. This ensures that you can quickly recover and continue your work without interruption.

Following these best practices will help you maintain a secure and efficient workflow, ensuring that your SSH keys are always protected and up-to-date.


Creating and configuring an SSH key in GitLab is a straightforward process that significantly enhances the security and efficiency of your Git operations. By following the steps outlined in this guide, you can seamlessly generate an SSH key pair, add the public key to your GitLab account, and configure your local environment to use this key for secure communication with your repositories. This not only simplifies your workflow but also ensures that your code remains protected. Remember, keeping your private key secure is crucial to maintaining the integrity of your SSH setup. Happy coding!

Frequently Asked Questions

What is an SSH key?

An SSH key is a pair of cryptographic keys used to authenticate a user in SSH protocol, providing a secure way to access and manage remote systems.

Why should I use SSH keys in GitLab?

Using SSH keys in GitLab enhances security by providing a more secure authentication method compared to traditional username and password.

How do I generate an SSH key on Windows?

To generate an SSH key on Windows, open Command Prompt and run the command ‘ssh-keygen’. Follow the prompts to save the key and set a passphrase.

How do I add my SSH key to GitLab?

Log in to your GitLab account, navigate to Settings, go to the SSH Keys section, and paste your public SSH key into the provided field.

What should I do if I encounter issues with my SSH key?

If you encounter issues with your SSH key, verify the key fingerprint, test the SSH connection, and check for any common troubleshooting steps.

Can I use multiple SSH keys with GitLab?

Yes, you can create and configure multiple SSH keys for different repositories or purposes in GitLab by updating your SSH config file.

How often should I update my SSH keys?

It is recommended to regularly update your SSH keys, at least once a year, to ensure ongoing security.

What is the benefit of using a passphrase for my SSH key?

Using a passphrase adds an extra layer of security, protecting your private key even if it is compromised.

You may also like...