RandomKeygen

SSH Key Setup Guide

Complete step-by-step SSH key setup guide for Windows, Mac, and Linux. Learn to generate, configure, and troubleshoot SSH keys for GitHub, GitLab, and secure server access.

What are SSH Keys?

SSH (Secure Shell) keys are a secure way to authenticate with remote servers and services like GitHub, GitLab, and cloud platforms. Instead of typing passwords, SSH keys use cryptographic key pairs to verify your identity.

🔑 Public Key

Shared with servers and services. Safe to copy and paste anywhere. Acts like a padlock that others can see.

🔐 Private Key

Kept secret on your computer. Never share this! Acts like the key that opens the padlock.

Choose Your Operating System

Step-by-Step Setup

Step 1: Generate Your SSH Key

Option A: Using Windows Terminal or PowerShell (Recommended)

Generate Ed25519 key (most secure and fast)

$ssh-keygen -t ed25519 -C '[email protected]'

If your system doesn't support Ed25519, use RSA instead:

Generate 4096-bit RSA key (older systems)

$ssh-keygen -t rsa -b 4096 -C '[email protected]'

Option B: Using Git Bash

If you have Git for Windows installed, open Git Bash and use the same commands above.

⚡ During Key Generation:

  • File location: Press Enter to use default location (~/.ssh/id_ed25519)
  • Passphrase: Enter a strong passphrase for extra security (recommended)
  • Confirm passphrase: Enter the same passphrase again

Step 2: Add Key to SSH Agent

Start the SSH agent and add your key:

Start SSH agent

$eval $(ssh-agent -s)

Add your SSH key to the agent

$ssh-add ~/.ssh/id_ed25519

If you used RSA, replace id_ed25519 with id_rsa

Step 3: Copy Your Public Key

Copy your public key to clipboard:

Copy public key to clipboard (Windows)

$clip < ~/.ssh/id_ed25519.pub

Alternative method if clip doesn't work:

Display public key to copy manually

$cat ~/.ssh/id_ed25519.pub

Platform Setup

🐙 GitHub Setup

  1. Go to GitHub SSH Settings
  2. Click "New SSH key"
  3. Give it a descriptive title (e.g., "My Laptop - 2024")
  4. Paste your public key into the "Key" field
  5. Click "Add SSH key"
  6. Test with: ssh -T [email protected]

🦊 GitLab Setup

  1. Go to GitLab SSH Keys
  2. Paste your public key into the "Key" field
  3. Add a descriptive title
  4. Set expiration date (optional but recommended)
  5. Click "Add key"
  6. Test with: ssh -T [email protected]

☁️ Cloud Providers

AWS:

Import key in EC2 Console → Key Pairs → Import Key Pair

Google Cloud:

Add in Compute Engine → Metadata → SSH Keys

DigitalOcean:

Add in Account → Security → SSH Keys

🖥️ Your Own Server

  1. Connect to your server via password/existing method
  2. Create SSH directory: mkdir -p ~/.ssh
  3. Add your public key: echo "your-public-key" >> ~/.ssh/authorized_keys
  4. Set permissions: chmod 600 ~/.ssh/authorized_keys
  5. Set directory permissions: chmod 700 ~/.ssh

Testing Your Setup

Test GitHub Connection

Should return: Hi username! You've successfully authenticated...

$ssh -T [email protected]

Test GitLab Connection

Should return: Welcome to GitLab, username!

$ssh -T [email protected]

Clone a Repository

Clone using SSH instead of HTTPS

$git clone [email protected]:username/repository.git

Common Issues & Solutions

❌ "Permission denied (publickey)"

Causes & Solutions:

  • SSH agent not running: Run eval $(ssh-agent -s)
  • Key not added to agent: Run ssh-add ~/.ssh/id_ed25519
  • Wrong key file: Check if you're using the right key name
  • Public key not added to platform: Re-add your public key

⚠️ "Could not open a connection to your authentication agent"

Solution: Start the SSH agent first:

$eval $(ssh-agent -s)

Then add your key: ssh-add ~/.ssh/id_ed25519

ℹ️ "Host key verification failed"

Solution: Remove the problematic host key:

$ssh-keygen -R hostname-or-ip

Then try connecting again to accept the new host key.

💡 Debug Connection Issues

Use verbose mode to see what's happening:

$ssh -vT [email protected]

This will show detailed connection information to help debug issues.

Security Best Practices

🔒 Key Security

  • Always use a strong passphrase for your private key
  • Never share your private key with anyone
  • Use Ed25519 keys for better security and performance
  • Generate separate keys for different purposes if needed
  • Regularly rotate your SSH keys (annually)

⚙️ Configuration Tips

  • Set up SSH config file (~/.ssh/config) for convenience
  • Use different keys for personal and work accounts
  • Set key expiration dates where supported
  • Keep your SSH client updated
  • Monitor your account's SSH key list regularly

Advanced: SSH Config File

Create a ~/.ssh/config file to simplify SSH connections and manage multiple accounts:

~/.ssh/config
# Personal GitHub account
Host github.com
  HostName github.com
  User git
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519

# Work GitHub account
Host github-work
  HostName github.com
  User git
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519_work

# GitLab
Host gitlab.com
  HostName gitlab.com
  User git
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519

# Custom server
Host myserver
  HostName your-server.com
  User yourusername
  Port 22
  IdentityFile ~/.ssh/id_ed25519
  ForwardAgent yes

Usage: With this config, you can simply use git clone github-work:company/repo.gitor ssh myserver instead of typing full commands.

Related Tools

SSH Key Generator

Generate SSH key pairs online

Password Generator

Create strong passphrases for your keys

PGP Key Generator

Generate PGP keys for encryption

Security Reminder: Your private SSH key is like a password to all your accounts. Never share it, always use a passphrase, and store it securely. If you suspect your key has been compromised, immediately remove it from all services and generate a new one.