How to Add an SSH Key to GitLab in 2 Ways?

In this guide, I’ll show you exactly how to add an SSH key to GitLab using two reliable methods. We’ll also generate a key pair and test the connection.

What Is an SSH Key?

An SSH key is a pair of cryptographic keys. One key is private and stays on your computer. The other is public and you share it with services like GitLab. Think of it as a lock and key. Your private key acts as the key. The public key is the lock that you give to GitLab. When you connect, GitLab uses your public key to send a challenge. Only your private key can answer correctly. This proves your identity without a password. SSH keys come in different types, such as RSA and Ed25519. Ed25519 is modern and more secure. You will create this pair in the next section.

Why Use SSH Keys with GitLab?

Using SSH keys with GitLab offers both security and convenience.

• You no longer type your password every time you push or pull.
• SSH keys are also resistant to brute‑force attacks because they use complex encryption. Password‑based authentication, even with two‑factor, can be phished.
• Many automated scripts and CI/CD pipelines rely on SSH keys. They let your tools interact with GitLab without human intervention.

So, whether you’re a solo developer or part of a team, SSH keys make life simpler.

How to Generate an SSH Key Pair?

Let’s create your own SSH key pair. Open your terminal.

First, check for existing keys by running ls -al ~/.ssh. If you see files like id_ed25519 and id_ed25519.pub, you already have a key. You can use that. Otherwise, we’ll generate a new one.

The command uses ssh-keygen. For a secure Ed25519 key, type ssh-keygen -t ed25519 -C "your_email@example.com". Replace the email with the one you use for GitLab. Press Enter.

You will be asked where to save the file. The default location (~/.ssh/id_ed25519) is fine. Next, you can set a passphrase for extra security. If you set one, you must enter it each time you use the key.

Some people skip this for automation. For now, press Enter twice for an empty passphrase. Your key pair is created. The public key has the .pub extension. To view it, run cat ~/.ssh/id_ed25519.pub. Copy the entire output. That string is what you will add to GitLab.

Method 1. Add SSH Key to GitLab via Web Interface

This method uses the GitLab web interface. It’s the simplest way and works for any user.

1. Log in to your GitLab account. In the top‑right corner, click your avatar.

2. A dropdown appears. Select Preferences. On the left sidebar, click SSH Keys.

3. You now see a form. Paste your public key into the Key box. The key starts with ssh-ed25519 or ssh-rsa and ends with your email.

4. Below that, fill in the Title field. Give it a meaningful name, like “My Laptop key”. This helps you identify it later.

5. Optionally, you can set an expiration date.

6. Once you are done, click the Add key button.

7. GitLab may ask for your password again, just to confirm your identity.

8. After that, you should see the new key listed under “Your SSH keys”. That’s it! You just connected your machine to GitLab securely.

Sometimes a copy‑paste error can sneak in. Ensure there are no extra spaces or line breaks in the key field. If the Add key button remains grayed out, check that the key format is correct. Also, make sure you pasted the entire key. It’s easy to miss the first or last characters. Once added, you can move on to testing the connection. This method never fails if you follow the steps.

Method 2. Add SSH Key to GitLab via API

You’ll need a personal access token with api scope. In GitLab, visit Preferences > Access Tokens. Create a token with the api scope and copy it immediately. Once you have the token, open a terminal and grab your public key with cat ~/.ssh/id_ed25519.pub. Keep that output handy.

Now, we craft a curl request. The old way uses --data but that can break your key. Why? SSH public keys contain characters like +, /, and =. In URL‑encoded form, + becomes a space and / escapes cause trouble. A better approach is --data-urlencode, which automatically encodes the value. Here is the safe command:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --data-urlencode "title=My API key" \
  --data-urlencode "key=$(cat ~/.ssh/id_ed25519.pub)" \
  "https://gitlab.com/api/v4/user/keys"

Replace <your_access_token> with your real token. The $(cat ~/.ssh/id_ed25519.pub) reads your public key file and passes it as the key parameter. If you prefer to paste manually, you must percent‑encode the key yourself—look for online tools that URL‑encode a string. However, the --data-urlencode method is almost foolproof. After running the command, a successful response shows JSON with your key’s id and title. If you see an error, double‑check that the token hasn’t expired and that you didn’t accidentally mix up the private and public key.

Administrators can also add a key for another user by changing the endpoint to /api/v4/users/:user_id/keys. Provide the user’s numeric ID. For your own account, the /user/keys endpoint is all you need. This method works on self‑hosted GitLab as well—just replace gitlab.com with your server’s domain. Keep your token safe; restrict its scope and set an expiration date. After adding via API, proceed to the connection test.

How to Test Your SSH Connection?

In your terminal, type ssh -T git@gitlab.com. This command attempts a connection to GitLab using your SSH key.

The first time, you might see a message asking to confirm the host. Type yes and press Enter.

If the key is set up correctly, GitLab replies with a welcome message. It looks like: “Welcome to GitLab, @username!”. That confirms your key is accepted. If you get “Permission denied (publickey)”, something is wrong. Check that you added the correct public key.

Also, ensure your SSH agent is running: eval "$(ssh-agent -s)" then ssh-add ~/.ssh/id_ed25519. Try the test command again. Most issues stem from a simple copy‑paste mistake.

Testing the API‑added key follows the same steps. The SSH client doesn’t care how the key got to GitLab. So this single test covers both methods. Once you see the welcome message, you can push, pull, and clone with confidence. No more password prompts.

Adding SSH Key to GitLab FAQs

Q1: Can I add more than one SSH key to my GitLab account?
Yes, GitLab lets you add many keys, which is perfect when you use multiple machines. Just repeat the add process for each device.

Q2: My SSH key isn’t working. What should I check first?
Run ssh -T git@gitlab.com for a specific error message, then follow the numbered checks in the troubleshooting section above for a full walkthrough.

Q3: How do I remove an old SSH key from GitLab?
Go to Preferences > SSH Keys, locate the key, and click Remove. Revoked keys lose access immediately.

Conclusion

Adding an SSH key to GitLab is a small task with big rewards. Now you can avoid password prompts and work faster. Both the web UI and API methods are reliable. Pick the one that fits your workflow. Test your connection, and then forget about authentication issues. Happy coding!