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
| Feature | HTTPS | SSH |
|---|---|---|
| Login method | Username and token | Key pair |
| Setup effort | Low | One-time key creation |
| Prompts during push | Common without a credential helper | None after setup |
| Clone URL style | https://gitlab.com/group/project.git | git@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
- Print the public key in your terminal:
cat ~/.ssh/id_ed25519.pub - Copy the whole line. It starts with ssh-ed25519 and ends with your email label.
- Select your avatar in the top-left corner and open Preferences and select SSH Keys.
- Paste the key into the Key box.
- Type a clear title such as "Office Laptop".
- Pick an expiration date to limit long-term risk.
- 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
| Message | Meaning | Fix |
|---|---|---|
| Permission denied (publickey) | GitLab found no matching public key | Add the key in Preferences and run ssh-add |
| Host key verification failed | The saved server fingerprint changed | Confirm the official fingerprint and remove the old line from known_hosts |
| Bad permissions on key file | Other users can read the private key | Run 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.
