When working with GitHub, SSH authentication is the most secure and reliable way to interact with repositories. However, SSH issues often arise due to misconfigured or conflicting keys—especially when switching machines or accounts.

This blog walks through a clean, from-scratch setup of GitHub SSH authentication, ensuring a reliable development environment.

---

Why Use SSH with GitHub?

• No need to enter username/password on every push

• More secure than HTTPS tokens

• Industry-standard for professional workflows

• Required when working with multiple repositories or automation

---

Prerequisites

• A GitHub account

• Git installed

• Terminal access (Linux / macOS / Windows with WSL or Git Bash)

---

Step 0: Clean Existing SSH Configuration (Optional but Recommended)

If you want to start completely fresh:

rm -rf ~/.ssh mkdir ~/.ssh chmod 700 ~/.ssh

This ensures no old or conflicting SSH keys remain.

---

Step 1: Generate a New SSH Key

GitHub recommends Ed25519, which is secure and fast.

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

When prompted:

• File location → Press Enter to use default

• Passphrase → Optional but recommended

This creates:

• Private key: ~/.ssh/id_ed25519

• Public key: ~/.ssh/id_ed25519.pub

---

Step 2: Start the SSH Agent

The SSH agent manages your keys securely in memory.

eval "$(ssh-agent -s)"

---

Step 3: Add the SSH Key to the Agent

ssh-add ~/.ssh/id_ed25519

Verify:

ssh-add -l

You should see your key listed.

---

Step 4: Add the SSH Key to GitHub

Copy the public key:

cat ~/.ssh/id_ed25519.pub

Then:

1. Go to GitHub → Settings

2. Open SSH and GPG keys

3. Click New SSH key

4. Title: Personal Laptop

5. Paste the key

6. Save

⚠️ Never upload your private key (id_ed25519).

---

Step 5: Test SSH Authentication

ssh -T git@github.com

Expected output:

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

This confirms GitHub recognizes your SSH key.

---

Step 6: Configure Git Identity

Set your personal Git identity:

git config --global user.name "John Doe" git config --global user.email "johndoe@email.com"

Verify:

git config --global --list

---

Step 7: Push a Repository Using SSH

Inside your project directory:

git init git add . git commit -m "Initial commit" git branch -M main git remote add origin git@github.com:username/repository.git git push -u origin main

---

Common Errors and Fixes

❌ Permission denied (publickey)

• SSH key not added to GitHub

• SSH agent not running

• Wrong repository URL

❌ Works with ssh -T but not git push

• Repository does not exist

• Pushing to the wrong GitHub account or org

---

Best Practices

• Use one SSH key per device

• Use separate keys for work and personal accounts

• Name keys clearly (id_ed25519_personal, id_ed25519_work)

• Never commit or share private keys

---

Conclusion

A clean SSH setup eliminates most GitHub authentication problems. By regenerating keys, using the SSH agent properly, and verifying access early, developers can avoid hours of debugging and ensure a smooth Git workflow.

This setup is simple, secure, and production-ready.