GitHub SSH Setup Guide (Mac & Windows)

Why SSH Instead of HTTPS?

• No more password/token authentication headaches
• No issues with credential caching problems
• More secure and convenient once set up
• One-time setup that works forever

Step 1: Generate SSH Key

Mac/Linux

Open Terminal and run:

ssh-keygen -t ed25519 -C "your-email@example.com"

Windows

Open PowerShell or Git Bash and run:

ssh-keygen -t ed25519 -C "your-email@example.com"

Important: Use the same email address associated with your GitHub account.

When prompted:

• File location: Just press Enter (uses default location)
• Passphrase: You can press Enter for no passphrase, or create one for extra security

You should see output like:

Your identification has been saved in /Users/yourname/.ssh/id_ed25519      # Mac
Your identification has been saved in C:\Users\yourname\.ssh\id_ed25519    # Windows
Your public key has been saved in [same path].pub

Step 2: Add SSH Key to SSH Agent

Mac

# Start the SSH agent
eval "$(ssh-agent -s)"

# Add your SSH key to the agent
ssh-add ~/.ssh/id_ed25519

Windows (PowerShell)

# Start the SSH agent (run as Administrator if needed)
Start-Service ssh-agent

# Add your SSH key to the agent
ssh-add ~/.ssh/id_ed25519

Windows (Git Bash)

# Start the SSH agent
eval "$(ssh-agent -s)"

# Add your SSH key to the agent
ssh-add ~/.ssh/id_ed25519

If you get a "No such file" error, your key might be named differently. Check with:

• Mac/Linux: ls ~/.ssh/
• Windows: dir ~/.ssh/ or ls ~/.ssh/ (in Git Bash)

Step 3: Copy Public Key to Clipboard

Mac

pbcopy < ~/.ssh/id_ed25519.pub

Windows (PowerShell)

Get-Content ~/.ssh/id_ed25519.pub | Set-Clipboard

Windows (Git Bash)

clip < ~/.ssh/id_ed25519.pub

Manual Method (Any OS)

If clipboard commands don't work:

cat ~/.ssh/id_ed25519.pub

Then manually select and copy the output.

Don't paste it anywhere yet!

Step 4: Add SSH Key to GitHub

1. Go to GitHub.com and sign in
2. Click your profile picture (top right) → Settings
3. In the left sidebar, click SSH and GPG keys
4. Click New SSH key
5. Give it a title like "My MacBook" or "My Windows Laptop"
6. In the "Key" field, paste your key (Ctrl+V or Cmd+V)
7. Click Add SSH key

Step 5: Test Your Connection

All Operating Systems

ssh -T git@github.com

You should see a message like:

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

If you get a "Permission denied" error, double-check the previous steps.

Step 6: Update Your Repository URLs

For any existing repositories, change from HTTPS to SSH:

# Check current URL
git remote -v

# If it shows https://github.com/..., change it:
git remote set-url origin git@github.com:username/repository-name.git

# Verify the change
git remote -v

Step 7: Clone New Repositories with SSH

From now on, always use the SSH URL when cloning:

# ✅ Correct (SSH)
git clone git@github.com:username/repository-name.git

# ❌ Avoid (HTTPS)
git clone https://github.com/username/repository-name.git

How to get SSH URL: On any GitHub repository page, click the green "Code" button and select "SSH" tab.

Troubleshooting

"Permission denied (publickey)" Error

Mac/Linux:

# Make sure your key is added to the SSH agent
ssh-add -l

# If empty, add your key again
ssh-add ~/.ssh/id_ed25519

Windows:

# Check if key is loaded
ssh-add -l

# If empty or error, restart SSH agent and add key
# In PowerShell (as Administrator):
Start-Service ssh-agent
ssh-add ~/.ssh/id_ed25519

# Or in Git Bash:
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

"Could not open a connection to your authentication agent"

Mac/Linux:

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

Windows (PowerShell):

Start-Service ssh-agent
ssh-add ~/.ssh/id_ed25519

Windows (Git Bash):

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

Still Having Issues?

1. Make sure you're using the SSH URL format: git@github.com:user/repo.git
2. Verify your key is on GitHub (Settings → SSH and GPG keys)
3. Test connection again: ssh -T git@github.com
4. On Windows, try using Git Bash instead of PowerShell

Clear Old HTTPS Credentials (If Needed)

Mac:

git config --global --unset credential.helper
# Also delete "github.com" entries from Keychain Access app

Windows:

git config --global --unset credential.helper
# Also check Windows Credential Manager and remove GitHub entries

Quick Reference

One-Time Setup = No More Authentication Headaches! 🎉