The Complete Guide to Setting Up SSH Keys on Ubuntu, Windows, and macOS (With GitLab Integration)

AsifDesai

— 2 min read
The Complete Guide to Setting Up SSH Keys on Ubuntu, Windows, and macOS (With GitLab Integration)
If you're a developer working with Git, remote servers, or CI/CD pipelines, SSH keys are essential.

Step 1: Understand What SSH Is

SSH stands for Secure Shell.
It is a secure protocol used to:

  • Connect to remote servers
  • Clone Git repositories
  • Push and pull code securely
  • Deploy applications

Instead of using passwords, SSH uses cryptographic key pairs.

Step 2: Understand SSH Key Pair

When you create an SSH key, two files are generated:

FilePurpose
id_ed25519Private key (Keep secret ❌ Never share)
id_ed25519.pubPublic key (Safe to share ✅)

How it works:

  1. You give your public key to GitLab.
  2. GitLab stores it.
  3. When you connect, GitLab verifies you using your private key.
  4. If matched → Access granted.

    No password needed.

Step 3: Why We Use SSH in GitLab

GitLab is used for:

  • Hosting repositories
  • CI/CD
  • Version control
  • Collaboration

Without SSH (using HTTPS):

git clone https://gitlab.com/username/project.git
Every push asks for username & password.

With SSH:git clone git@gitlab.com:username/project.git
Push → Done instantly 🚀
That’s why developers prefer SSH.

Step 4: Generate SSH Key on Ubuntu

1️⃣ Open Terminal

Press:Ctrl + Alt + T

2️⃣ Check If SSH Already Exists
ls -al ~/.ssh
If folder doesn’t exist → no problem.

3️⃣ Generate New SSH Key

Recommended modern algorithm:
ssh-keygen -t ed25519 -C "your_email@example.com"
If not supported:
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
Press Enter to accept default location:/home/username/.ssh/id_ed25519
Set passphrase (optional but recommended).

4️⃣ Start SSH Agent
eval "$(ssh-agent -s)"

5️⃣ Add Key to SSH Agent
ssh-add ~/.ssh/id_ed25519

6️⃣ Copy Public Key
cat ~/.ssh/id_ed25519.pub
Copy the entire output.

Step 5: Generate SSH Key on Windows

  1. Install Git for Windows
  2. Open Git Bash

Run:ssh-keygen -t ed25519 -C "your_email@example.com"
Keys are stored in:C:\Users\YourUsername\.ssh\

View public key:cat ~/.ssh/id_ed25519.pub

Option 2: Using PowerShell

Open PowerShell and run:

ssh-keygen -t ed25519 -C "your_email@example.com"
Same process..

Step 6: Generate SSH Key on macOS

1️⃣ Open Terminal

Cmd + Space → Terminal

2️⃣ Generate Key

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

3️⃣ Start SSH Agent

eval "$(ssh-agent -s)"

4️⃣ Add Key

ssh-add ~/.ssh/id_ed25519

5️⃣ Copy Public Key

pbcopy < ~/.ssh/id_ed25519.pub

Step 7: Add SSH Key to GitLab

  1. Login to GitLab
  2. Click Profile → Preferences
  3. Click SSH Keys
  4. Paste copied public key
  5. Click Add Key

Now GitLab trusts your machine.

Step 8: Test SSH Connection

Run: ssh -T git@gitlab.com
If successful, you’ll see:Welcome to GitLab!

Step 9: Clone Using SSH

Instead of HTTPS:
git clone git@gitlab.com:username/project.git
Now: git push
No password required.

Step 10: Security Best Practices

✔ Use ed25519
✔ Protect private key
✔ Add passphrase
✔ Never share private key
✔ Set correct permissions (Linux/macOS):

chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519

Bonus: How SSH Works Internally

  1. Client connects to GitLab
  2. GitLab checks public key
  3. GitLab sends encrypted challenge
  4. Your private key decrypts it
  5. Verified → Access granted

This uses asymmetric cryptography — extremely secure.

Final Conclusion

Setting up SSH keys:

  • Improves security
  • Removes password dependency
  • Enables automation
  • Essential for DevOps
  • Industry best practice

If you are serious about professional development, SSH is not optional — it’s foundational

Read more