How to Add SSH Keys to GitLab?

SSH keys are a secure and efficient way to authenticate with GitLab repositories. They allow you to establish a secure connection between your local machine and GitLab, eliminating the need to enter your username and password each time you push or pull changes.

In this post, we’ll walk you through the steps to generate, add, and test SSH keys for GitLab, ensuring you can interact with your repositories securely and seamlessly.

Why Use SSH Keys with GitLab?

GitLab offers multiple methods for authentication when interacting with repositories, such as HTTPS and SSH. While HTTPS is easier to set up initially, SSH provides a more secure and convenient option for ongoing authentication. Here’s why SSH is preferred by many developers:

1. Security: SSH keys are more secure than passwords and reduce the risk of unauthorized access.
2. Convenience: Once set up, SSH allows for password-less authentication, making it quicker to interact with repositories.
3. Automated Authentication: SSH keys enable automated processes (such as CI/CD) to interact with GitLab repositories without manual intervention.

---

Step 1: Check for Existing SSH Keys

Before generating a new SSH key, it’s a good idea to check if you already have one on your local machine. Here’s how you can do that:

1. Open Git Bash (Windows) or your terminal (Linux/macOS).
2. Run the following command to see if there are any existing SSH keys:

   ls -al ~/.ssh

3. Look for files such as id_rsa and id_rsa.pub. The .pub file is the public key, which is what you’ll add to GitLab. If these files exist, you can skip generating a new key and use the existing ones.

---

Step 2: Generate a New SSH Key

If you don’t have an existing SSH key or want to generate a new one, follow these steps:

1. Open Git Bash (Windows) or your terminal (Linux/macOS).
2. Run the following command to generate a new SSH key:

   ssh-keygen -t rsa -b 4096 -C "[email protected]"

Replace "[email protected]" with the email associated with your GitLab account.

• Explanation:
  • -t rsa: Specifies the type of key to create (RSA).
  • -b 4096: Specifies the key length (4096 bits for stronger encryption).
  • -C: Adds a comment (your email) to the key for identification purposes.

1. When prompted, choose the default file location for the key by pressing Enter (usually ~/.ssh/id_rsa), or provide a custom name if you prefer.
2. If you want to add an extra layer of security, enter a passphrase. Otherwise, press Enter to leave it empty. Your new SSH key pair will be generated, with the private key stored in the default location (e.g., ~/.ssh/id_rsa) and the public key stored in ~/.ssh/id_rsa.pub.

---

Step 3: Add Your SSH Key to the SSH Agent

The SSH agent manages your SSH keys and allows you to use them without entering the passphrase each time.

1. Start the SSH agent by running the following command:

   eval "$(ssh-agent -s)"

2. Add your SSH private key to the agent:

   ssh-add ~/.ssh/id_rsa

This ensures that the agent is aware of your private key and can use it for authentication.

---

Step 4: Copy the SSH Public Key

Now, you need to copy your SSH public key (id_rsa.pub) to add it to GitLab.

1. Run the following command to copy the SSH key to your clipboard:

• On Windows (Git Bash): clip < ~/.ssh/id_rsa.pub
• On Linux/macOS: cat ~/.ssh/id_rsa.pub | pbcopy This command copies the contents of the public key to your clipboard.

1. If the above command doesn’t work, you can manually open the id_rsa.pub file with a text editor and copy its contents.

---

Step 5: Add Your SSH Key to GitLab

Now that your public key is copied, you can add it to GitLab.

1. Log in to your GitLab account and navigate to your Profile Settings.
2. In the left sidebar, click on SSH Keys under the Access Tokens section.
3. In the Title field, you can add a description for the key (e.g., “My Laptop” or “Work Computer”).
4. Paste your SSH public key into the Key field.
5. Click the Add key button to save your SSH key.

---

Step 6: Test the SSH Connection

To ensure everything is set up correctly, you should test the SSH connection to GitLab.

1. Open your terminal or Git Bash.
2. Run the following command to test the connection:

   ssh -T [email protected]

3. The first time you connect, you may see a message asking if you want to continue connecting. Type yes and press Enter.
4. If everything is set up correctly, you will see a success message like:

   Welcome to GitLab, @your_username!

This confirms that your SSH key is working and GitLab is recognizing your machine for authentication.

---

Troubleshooting

If you encounter any issues during this process, here are a few things to check:

1. SSH Agent: Make sure the SSH agent is running and has your key added. You can check with the command:

   ssh-add -l

2. Correct Key: Verify that you’ve copied the correct SSH key to GitLab, and that there are no extra spaces or line breaks.
3. File Permissions: Ensure your .ssh folder and key files have the correct permissions. You can fix them with:

   chmod 700 ~/.ssh
   chmod 600 ~/.ssh/id_rsa

---

Conclusion

Adding SSH keys to GitLab is an essential step for securely authenticating with your repositories. By following this guide, you can generate an SSH key, add it to your GitLab account, and streamline your workflow by avoiding the need to enter your username and password repeatedly. With SSH set up, you can focus more on development and less on authentication, improving your overall efficiency and security when working with GitLab.