SSH Setup for GitHub - Cross-Platform Guide
SSH Setup for GitHub - Cross-Platform Guide
This guide works for macOS, Windows (PowerShell), and Windows Subsystem for Linux (WSL).
Why SSH?
Since August 2021, GitHub no longer accepts passwords for Git operations. You have two options:
- Personal Access Tokens (PAT) - tokens you manually create and enter as passwords
- SSH Keys - cryptographic keys that authenticate automatically (recommended)
SSH is preferred because it’s more secure and convenient once set up.
Step 1: Check for Existing SSH Keys
All Platforms (macOS, Windows PowerShell, WSL):
ls -la ~/.ssh
If you see files like id_ed25519 and id_ed25519.pub, you already have SSH keys. Skip to Step 4.
Step 2: Generate SSH Keys
All Platforms:
ssh-keygen -t ed25519 -C "your.email@example.com"
What this does:
-t ed25519creates a modern, secure key type-Cadds your email as a comment
When prompted:
- File location: Press Enter to use the default (
~/.ssh/id_ed25519)- macOS/WSL:
~=/Users/yourusername/.ssh/or/home/yourusername/.ssh/ - Windows PowerShell:
~=C:\Users\yourusername\.ssh\
- macOS/WSL:
- Passphrase: Press Enter for no passphrase, or add one for extra security
Step 3: Start SSH Agent and Add Key
macOS and WSL:
# Start the SSH agent
eval "$(ssh-agent -s)"
# Add your key to the agent
ssh-add ~/.ssh/id_ed25519
Windows PowerShell:
# Start the SSH agent service
Get-Service ssh-agent | Set-Service -StartupType Manual
Start-Service ssh-agent
# Add your key to the agent
ssh-add $env:USERPROFILE\.ssh\id_ed25519
Step 4: Copy Your Public Key
macOS:
pbcopy < ~/.ssh/id_ed25519.pub
WSL/Linux:
cat ~/.ssh/id_ed25519.pub
# Copy the output manually
Windows PowerShell:
Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub | Set-Clipboard
Alternative for all platforms:
cat ~/.ssh/id_ed25519.pub
Then manually copy the output (starts with ssh-ed25519).
Step 5: Add Key to GitHub
- Go to GitHub.com and sign in
- Click your profile picture → Settings
- In the left sidebar, click SSH and GPG keys
- Click New SSH key
- Give it a title (like “My Laptop” or “Work Computer”)
- Paste your public key in the “Key” field
- Click Add SSH key
Step 6: Test Your Connection
All Platforms:
ssh -T git@github.com
Expected output:
Hi yourusername! You've successfully authenticated, but GitHub does not provide shell access.
If you see a warning about host authenticity, type yes and press Enter.
Step 7: Use SSH URLs
When cloning repositories, use the SSH URL instead of HTTPS:
# SSH URL (use this)
git clone git@github.com:username/repository.git
# HTTPS URL (avoid this)
git clone https://github.com/username/repository.git
Troubleshooting
“Permission denied (publickey)”
- Make sure you copied the public key (
.pubfile) to GitHub - Verify the SSH agent is running:
ssh-add -l - Re-add your key:
ssh-add ~/.ssh/id_ed25519(orssh-add $env:USERPROFILE\.ssh\id_ed25519on Windows PowerShell)
“Could not open a connection to your authentication agent” (Windows)
- Run PowerShell as Administrator
- Restart the SSH agent service:
Stop-Service ssh-agent Start-Service ssh-agent
Key not found
- Make sure you’re in the right directory:
cd ~ - Check the exact filename:
ls ~/.ssh/(orls $env:USERPROFILE\.sshon Windows PowerShell) - Use the correct path in
ssh-add
Platform-Specific Notes
macOS
- SSH agent typically starts automatically
- Keys are stored in the system keychain
Windows PowerShell
- SSH agent is available in Windows 10/11 by default
- May need to run as Administrator for service commands
WSL (Windows Subsystem for Linux)
- Works exactly like Linux
- Keys are separate from Windows PowerShell keys
- SSH agent needs to be started each session (unless configured otherwise)
Security Best Practices
- Use a passphrase for your SSH key if you’re on a shared computer
- Don’t share your private key (
id_ed25519without.pub) - Use different keys for different services if needed
- Regularly rotate keys (yearly is reasonable)
- Remove old keys from GitHub when you no longer use them
That’s it! Once set up, you’ll never need to enter passwords for GitHub operations again.