🔐 GitLab SSH Setup — Windows & Linux/macOS¶

• Goal: create/load an SSH key, add it to GitLab, and verify with ssh -T git@gitlab.com.

Prereqs¶

• Git installed

  • Windows: [Git for Windows] (includes Git Bash + OpenSSH)

  • Linux/macOS: Git + OpenSSH are usually preinstalled

• A GitLab account

Check if you already have an SSH key¶

• Linux / macOS / Windows (Git Bash)

  ls -al ~/.ssh
  

• Windows (PowerShell)

  Get-ChildItem ~\.ssh
  

• Look for a key pair like id_ed25519 (private) and id_ed25519.pub (public).

• Typical locations:

  • Linux/macOS: ~/.ssh/

  • Windows: C:\Users\<You>\.ssh\

Generate a new key (if you don’t have one)¶

• Use Ed25519 as demo

• Linux / macOS / Windows (Git Bash) / - Windows (PowerShell)

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

• Result: id_ed25519 and id_ed25519.pub created in your ~/.ssh (or C:\Users\<You>\.ssh)

Start the SSH agent & add your key¶

• Linux / macOS / Windows (Git Bash)

  # start agent in this shell.
  eval "$(ssh-agent -s)"
  # add your key
  ssh-add ~/.ssh/id_ed25519
  

  • If you get “no such file,” double-check the path/filename.

• Windows (PowerShell)

  # make the agent run automatically
  Get-Service ssh-agent | Set-Service -StartupType Automatic
  Start-Service ssh-agent
  
  # add your key
  ssh-add $env:USERPROFILE\.ssh\id_ed25519
  

Copy your public key and add to GitLab¶

• Open the .pub file and copy all its contents

• Then in GitLab: User menu → Settings → SSH Keys → Add new key (paste, give a title, Save).

Test the connection¶

• Linux / macOS / Windows

  ssh -T git@gitlab.com
  

• Expected success message:

  Welcome to GitLab, @your-username!
  

• If you see Permission denied (publickey), the key either isn’t added to GitLab or not loaded in the agent.

Troubleshooting tips¶

• Agent says no identities → run ssh-add again (see Step 3)

• Permissions on Linux/macOS (rarely the issue on Windows)

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

• Multiple keys? Create ~/.ssh/config

  Host gitlab.com
      HostName gitlab.com
      User git
      IdentityFile ~/.ssh/id_ed25519
      IdentitiesOnly yes