GitLab SSH Keys

An SSH key pair lets your computer prove its identity to GitLab without a password prompt on every push or pull. The pair holds two files. The private key stays on your computer. The public key lives in your GitLab account.

Picture a padlock and a key. You hand GitLab a copy of the padlock (the public key) and keep the only key that opens it (the private key). Each time you connect, GitLab checks whether your key fits its padlock and lets you in when it does.

How the Connection Works

  YOUR COMPUTER                              GITLAB SERVER
  ┌──────────────────────┐                  ┌──────────────────────┐
  │ Private key          │                  │ Public key (stored)  │
  │ id_ed25519           │                  │ id_ed25519.pub       │
  │ never leaves your PC │                  │ added in Settings    │
  └──────────┬───────────┘                  └──────────┬───────────┘
             │                                         │
             │  1. "I am Riya. Solve this puzzle."     │
             │◄────────────────────────────────────────┤
             │  2. Private key solves the puzzle       │
             ├────────────────────────────────────────►│
             │  3. Public key confirms the answer      │
             │◄────────────────────────────────────────┤
             │     Access granted, no password typed   │

HTTPS and SSH Compared

FeatureHTTPSSSH
Login methodUsername and tokenKey pair
Setup effortLowOne-time key creation
Prompts during pushCommon without a credential helperNone after setup
Clone URL stylehttps://gitlab.com/group/project.gitgit@gitlab.com:group/project.git

Create Your Key Pair

Check for Existing Keys

Open a terminal and list the files in your SSH folder. A file named id_ed25519.pub means you already own a key.

ls ~/.ssh

Generate a New Key

Run the command below and replace the email with your own. The label after -C helps you recognize the key later.

ssh-keygen -t ed25519 -C "riya@example.com"

The tool asks two questions. Press Enter to accept the default file location. Type a passphrase to lock the private key, or press Enter to skip it. A passphrase adds a second layer of protection if someone copies your file.

Add the Public Key to GitLab

  1. Print the public key in your terminal: cat ~/.ssh/id_ed25519.pub
  2. Copy the whole line. It starts with ssh-ed25519 and ends with your email label.
  3. Select your avatar in the top-left corner and open Preferences and select SSH Keys.
  4. Paste the key into the Key box.
  5. Type a clear title such as "Office Laptop".
  6. Pick an expiration date to limit long-term risk.
  7. Select Add key.

Never paste the private key. The private key file has no .pub ending.

Test the Connection

ssh -T git@gitlab.com

The first connection shows a fingerprint question. Type yes to continue. A successful test prints a welcome message.

Welcome to GitLab, @riya!

Clone and Switch to SSH

Copy the SSH address from the project page by selecting Code and choosing Clone with SSH.

git clone git@gitlab.com:my-group/my-project.git

A project cloned with HTTPS can switch to SSH with one command.

git remote set-url origin git@gitlab.com:my-group/my-project.git

Load the Key with ssh-agent

The ssh-agent program remembers your passphrase while you work. You type the passphrase once per session.

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

Use Separate Keys for Separate Accounts

A developer with a work account and a personal account creates one key per account. A config file tells SSH which key belongs to which host name.

# File: ~/.ssh/config
Host gitlab-work
  HostName gitlab.com
  User git
  IdentityFile ~/.ssh/id_ed25519_work

Host gitlab-personal
  HostName gitlab.com
  User git
  IdentityFile ~/.ssh/id_ed25519_personal

Clone with the host alias to select the matching key.

git clone git@gitlab-work:my-group/my-project.git

Common Errors and Fixes

MessageMeaningFix
Permission denied (publickey)GitLab found no matching public keyAdd the key in Preferences and run ssh-add
Host key verification failedThe saved server fingerprint changedConfirm the official fingerprint and remove the old line from known_hosts
Bad permissions on key fileOther users can read the private keyRun chmod 600 ~/.ssh/id_ed25519

Key Safety Rules

  • Keep the private key on one trusted device.
  • Protect every private key with a passphrase.
  • Delete keys from GitLab when you retire a laptop.
  • Rotate keys on a regular schedule.
  • Never send a private key through chat or email.