How to Set Up SSH Keys for GitHub Without Losing Your Mind

SSH keys: you make two files. One stays on your machine and never fucking leaves (private key). The other goes to GitHub (public key). When you push code, they do cryptographic math together and GitHub says "yep, this is actually you."

Before you start, check this shit or you'll waste an hour

Windows users: PowerShell SSH is broken garbage. Download Git for Windows, use Git Bash, pretend PowerShell doesn't exist. I wasted 3 hours in 2024 trying to make PowerShell SSH work with Unicode passphrases - just fucking don't. If you're using WSL2, stick to the Linux SSH client but Windows Terminal vs Git Bash use different home directories - pick one and stick with it.

macOS users: Your SSH tools are built-in, but check if you're running ancient software:

ssh -V

If you see OpenSSH older than 6.5, you're living in 2013. ED25519 won't work and you'll get "unknown key type" errors that make no fucking sense. Current OpenSSH releases (9.6+ as of 2025) support ed25519 natively. Check the OpenSSH release history - ed25519 support was added in OpenSSH 6.5 (January 2014), and DSA support is finally being completely removed in 2025.

Linux users: If ssh-keygen says command not found, install OpenSSH: sudo apt install openssh-client (Ubuntu/Debian) or sudo yum install openssh-clients (RHEL/CentOS). Different distros package it differently - check pkgs.org for yours. Ubuntu 18.04 ships with OpenSSH 7.6 which supports ed25519 but I've had it randomly fail with Cisco AnyConnect VPN - took me 4 hours to figure out the corporate VPN was mangling SSH packets.

Key Types That Don't Suck

Use ed25519 keys. Period. GitHub deprecated DSA keys in March 2022 because they're cryptographically broken. RSA-2048 still works but it's like using Internet Explorer - technically functional but why would you?

• ed25519: Generates in 0.2 seconds, small keys, fast crypto - RFC 8709 standard
• RSA 4096-bit: Takes 30 seconds to generate, massive keys, but works on ancient systems - NIST approved
• RSA 2048-bit: What everyone used to use, still works but deprecated by 2030 - quantum vulnerable
• DSA: Dead since March 2022. GitHub returns "DSA keys are no longer supported" - SHA-1 collision attacks

Things That Will Bite You

Before you start generating keys and wonder why nothing works:

1. Use the right email: Match the email on your GitHub account or you'll spend an hour debugging why authentication fails. Check GitHub's SSH troubleshooting guide for common email issues.
2. Don't skip the passphrase: I don't care how tedious it seems, use one. The OWASP guide explains why passphrases matter.
3. Windows file permissions: Git Bash handles this, but if you're messing with WSL, chmod 600 your private key or SSH will refuse to use it. See Windows SSH permissions for WSL specifics. Windows Terminal vs Git Bash handle paths differently - stick with Git Bash.
4. Corporate networks: Some companies block port 22. You'll need to use HTTPS instead or configure SSH over HTTPS on port 443. Your corporate laptop probably has some security software that fucks with SSH. Check your company's firewall policies.
5. Multiple GitHub accounts: Each account needs its own SSH key. You cannot share them. Follow GitHub's multiple accounts guide carefully.

The whole process takes 10 minutes unless something breaks, then it's 2 hours of Stack Overflow and questioning your career choices.

Ready to Generate Keys? Platform Reality Check

You've confirmed your system has the right tools, you understand the key types, and you've mentally prepared for the platform-specific gotchas. Time for the actual SSH key generation and setup.

The commands are basically the same across platforms, but each operating system has its own special way of making simple things complicated. Windows has clipboard quirks and SSH agent that dies every reboot, macOS has Keychain integration that randomly breaks after OS updates, and Linux has the delightful variety of desktop environments that each handle SSH agent differently.

You understand what SSH keys are, you've checked your platform compatibility, and you know what's going to break. Time for the actual commands that will either work perfectly or send you down a 2-hour debugging rabbit hole where you question every life choice that led you to this moment.

Should take 5 minutes if you're lucky. Will take 2 hours if you're on corporate Windows and SSH decides to randomly break for no reason. Let's get this over with.

Step 1: Check What Keys You Already Have

Don't generate new keys if you already have working ones, you masochist:

ls -la ~/.ssh

Look for these files:

• id_ed25519 + id_ed25519.pub = modern ed25519 pair
• id_rsa + id_rsa.pub = old RSA pair that still works
• Anything ending in .pub is your public key, everything else is private

If you see id_ed25519 + id_ed25519.pub from 2023+, skip to Step 4. If you have old RSA keys or nothing, generate new ones. I used the same RSA-2048 key from 2019 until 2024 when GitHub started throwing deprecation warnings - don't be me.

Step 2: Generate New Keys (Replace Your Email)

Copy this exactly but use YOUR email (the one on your GitHub account):

ssh-keygen -t ed25519 -C \"your.actual.email@whatever.com\"

If you're stuck on OpenSSH 6.4 or older (how?), ed25519 won't work and you'll get this exact error:

unknown key type ed25519

Use RSA instead. Check OpenSSH compatibility to see which key types your version supports:

ssh-keygen -t rsa -b 4096 -C \"your.actual.email@whatever.com\"

Pro tip: If you're generating multiple keys for different accounts, name them specifically:

ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_work -C \"work@company.com\"
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_personal -C \"personal@gmail.com\"

What Happens During Generation

1. File location: Just press Enter unless you're doing something fancy - keys go in ~/.ssh/ by default. Read the SSH directory structure guide to understand the layout.
2. Passphrase: Use one. I don't care if it's annoying, use a passphrase. Follow NIST passphrase guidelines for security.
3. Confirm passphrase: Type the same thing again

You'll see some ASCII art and a fingerprint. That's normal. The fingerprint is how you identify this specific key later. Learn more about SSH key fingerprints and their purpose.

Step 3: Wake Up SSH Agent and Load Your Key

SSH agent handles your keys and remembers passwords so you don't type them every git command. Read about how SSH agent works to understand the process:

eval \"$(ssh-agent -s)\"

You should see Agent pid 12345 or similar. If you get "Could not open a connection to your authentication agent", SSH agent is dead - restart your terminal or run the eval command again. Check SSH agent troubleshooting for the full nightmare.

Now add your key to the agent:

macOS users (special snowflakes):

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

Windows/Linux users:

ssh-add ~/.ssh/id_ed25519

Type your passphrase when it asks. SSH agent remembers it until you restart. Learn about SSH agent forwarding if you need persistent sessions.

macOS Keychain Setup (Or It'll Break Later)

macOS needs special configuration or it forgets your keys after reboot. Create/edit ~/.ssh/config - see Apple's SSH documentation for details:

nano ~/.ssh/config

Add this:

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

Save and exit (Ctrl+X, then Y, then Enter` in nano). Read about SSH config file options to understand all available settings.

Step 4: Copy Your Public Key to Clipboard

Use the right command for your platform. Check platform-specific clipboard tools if these don't work:

Windows (Git Bash):

clip < ~/.ssh/id_ed25519.pub

macOS:

pbcopy < ~/.ssh/id_ed25519.pub

Linux (install xclip first if needed):

sudo apt install xclip
xclip -sel clip < ~/.ssh/id_ed25519.pub

Your public key is now in your clipboard. It looks like random garbage starting with ssh-ed25519 AAAAC3NzaC1... - that's correct. Read about SSH key formats to understand the structure.

Don't worry, the public key is safe to share. It's the private key (the one without .pub) that you guard with your life. Learn about public key cryptography to understand why this works. For additional security, consider SSH certificates in enterprise environments.

From Local Keys to GitHub Authentication

You've generated your SSH keys and gotten your SSH agent working. Now comes the crucial step: teaching GitHub to trust your machine. This is where the cryptographic handshake gets established - once GitHub knows your public key, it can verify that Git commands are actually coming from you.

Public key copied to clipboard? Perfect. Time to convince GitHub to trust your machine, which involves navigating their settings UI and hoping you don't fat-finger the paste operation.

This is the moment where SSH either works perfectly or fails in ways that make you question your life choices. In my experience, Windows fucks up 60% of the time, macOS breaks 30% of the time, Linux breaks 10% of the time but when it does, it's spectacularly fucked.

Step 5: Paste Your Key into GitHub

1. Go to github.com and log in
2. Click your profile picture → Settings → SSH and GPG keys
3. Click the green "New SSH key" button
4. Fill out the form:
   • Title: Something useful like "MacBook Pro 2025" or "Work Laptop" - not "My Key"
   • Key type: Leave it as "Authentication Key" (read about deploy keys vs auth keys)
   • Key: Paste that clipboard garbage you copied earlier (starts with ssh-ed25519)
5. Click "Add SSH key"
6. GitHub might ask for your password - type it in

The title matters when you have multiple keys and need to figure out which laptop is which when one gets stolen. Check GitHub's SSH key management guide for best practices.

Step 6: Test If SSH Actually Works

This is the moment of truth. Run this and cross your fingers:

ssh -T git@github.com

First time connecting, you'll get this scary message:

The authenticity of host 'github.com (140.82.112.4)' can't be established.
ED25519 key fingerprint is SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU.
Are you sure you want to continue connecting (yes/no/[fingerprint])?

Type yes and hit Enter. This is GitHub's actual fingerprint, not someone trying to hack you. Learn about SSH host key verification to understand this security check.

If it worked, you'll see:

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

See your actual username? SSH is working. See "Permission denied (publickey)"? You're fucked and headed to troubleshooting hell. See "ssh: connect to host github.com port 22: Connection refused"? Your corporate firewall is blocking SSH. For debugging, ssh -vT git@github.com dumps everything including "debug1: Offering RSA public key" lines.

Step 7: Switch Your Repos from HTTPS to SSH

Your existing repos are probably still using HTTPS (username/password). Fix that:

Check what you're currently using:

cd /path/to/your/repo
git remote -v

If you see https://github.com/..., change it to SSH:

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

Replace username/repository with your actual repo details, obviously. Read about Git remote URLs to understand the differences.

For new clones, use the SSH URL:

git clone git@github.com:username/repository.git

Learn about Git protocols to understand when to use SSH vs HTTPS.

Does It Actually Work? (Checklist)

Test these to confirm you didn't waste the last hour:

• ssh-add -l shows "3072 SHA256:abc123... your@email.com (RSA)" or similar
• ssh -T git@github.com shows "Hi yourusername!" not "Permission denied"
• git push works without password prompts
• Close terminal, reopen, test again (Windows SSH agent will probably be dead)

If any of these fail, something's broken and you get to debug SSH authentication like it's 2005. Check SSH debugging techniques and common Git issues.

SSH test failed? Congratulations, you've joined the "SSH broke for no reason" support group. Population: every developer who's ever tried to set up authentication. Time for the troubleshooting section that'll either save your sanity or destroy it completely.