Skip to main content

SSH Keys

Why SSH Keys?​

When you push to GitHub, you need to prove you're authorized to do so. The two options are:

  • HTTPS — uses your username + a personal access token (prompts every time unless cached)
  • SSH — uses a cryptographic key pair stored on your computer (authenticate once, never prompted again)

SSH is the preferred choice for day-to-day development. Once set up, git push and git pull just work.

How SSH Keys Work​

SSH uses a key pair:

  • Private key (id_ed25519) — stays on your computer, never shared
  • Public key (id_ed25519.pub) — added to GitHub

When you connect, GitHub encrypts a challenge with your public key. Only your private key can decrypt it — so GitHub knows it's really you, without you sending a password.

Step 1: Check for Existing Keys​

First, see if you already have SSH keys:

ls -la ~/.ssh

Look for files like id_ed25519, id_rsa, or id_ecdsa. If you see them, you might already be set up — skip to Step 3.

Step 2: Generate a New SSH Key​

Use Ed25519 (recommended — more secure and faster than RSA):

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

You'll be prompted:

Enter file in which to save the key (/Users/you/.ssh/id_ed25519): [press Enter]
Enter passphrase (empty for no passphrase): [optional but recommended]
Enter same passphrase again:
  • File location — press Enter to accept the default
  • Passphrase — adds an extra layer of security. If someone gets your private key, they still need the passphrase to use it. You'll be prompted once per session (managed by ssh-agent)

This creates two files:

  • ~/.ssh/id_ed25519 — your private key (never share this)
  • ~/.ssh/id_ed25519.pub — your public key (this goes on GitHub)

Step 3: Add Key to ssh-agent​

The ssh-agent holds your private key in memory so you don't re-enter the passphrase constantly:

macOS / Linux:

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

Windows (Git Bash):

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

macOS — persist across reboots (add to ~/.ssh/config):

Host github.com
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519

Then:

ssh-add --apple-use-keychain ~/.ssh/id_ed25519

Step 4: Add Public Key to GitHub​

Copy your public key to the clipboard:

# macOS
pbcopy < ~/.ssh/id_ed25519.pub

# Linux
xclip -selection clipboard < ~/.ssh/id_ed25519.pub
# or just print it and copy manually:
cat ~/.ssh/id_ed25519.pub

Then on GitHub:

  1. Go to Settings → SSH and GPG keys
  2. Click New SSH key
  3. Give it a descriptive title (e.g., "MacBook Pro — Work")
  4. Paste your public key
  5. Click Add SSH key

Step 5: Test the Connection​

ssh -T git@github.com

Expected output:

Hi mrizwanashiq! You've successfully authenticated, but GitHub does not provide shell access.

If you see this, SSH is working.

If you get "Permission denied"
  1. Make sure the key was added to ssh-agent: ssh-add -l
  2. Verify the public key is on GitHub (Settings → SSH keys)
  3. Check the remote URL uses SSH (not HTTPS)

Step 6: Use SSH Remote URLs​

When cloning, use the SSH URL (not HTTPS):

# SSH (use this)
git clone git@github.com:username/repo.git

# HTTPS (avoid if you want SSH auth)
git clone https://github.com/username/repo.git

If you already cloned with HTTPS, switch to SSH:

git remote set-url origin git@github.com:username/repo.git

# Verify
git remote -v
# origin  git@github.com:username/repo.git (fetch)
# origin  git@github.com:username/repo.git (push)

Multiple GitHub Accounts​

If you have work and personal GitHub accounts, use different SSH keys and configure ~/.ssh/config:

# Personal
Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_personal

# Work
Host github-work
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_work

For work repos, use github-work as the host:

git clone git@github-work:company/repo.git
# or update existing remote:
git remote set-url origin git@github-work:company/repo.git

Quick Reference​

# Generate key
ssh-keygen -t ed25519 -C "email@example.com"

# Start agent and add key
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

# Copy public key (macOS)
pbcopy < ~/.ssh/id_ed25519.pub

# Test connection
ssh -T git@github.com

# Check remote URL
git remote -v

# Switch remote to SSH
git remote set-url origin git@github.com:user/repo.git