GitHub SSH Setup Guide

Complete guide to setting up SSH keys for secure authentication with GitHub. SSH keys provide a secure way to authenticate without entering your password every time you push or pull from GitHub.

Why Use SSH?

Benefits:

🔐 More Secure - No password exposure

⚡ Faster - No need to enter credentials repeatedly

🤖 Automation-Friendly - Works great in CI/CD pipelines

🔑 Key-Based Auth - Uses public-key cryptography

📦 Multiple Accounts - Easy to manage multiple GitHub accounts

Table of Contents

Check for Existing SSH Keys

Generate New SSH Key

Add SSH Key to SSH Agent

Add SSH Key to GitHub

Test SSH Connection

Clone Repository Using SSH

Convert HTTPS to SSH

Multiple GitHub Accounts

Troubleshooting

Check for Existing SSH Keys {#check-existing-keys}

Before generating a new key, check if you already have SSH keys.

Linux/Mac

# ========== Check for existing SSH keys ==========
ls -al ~/.ssh

# Look for files like:
# id_rsa.pub
# id_ecdsa.pub
# id_ed25519.pub

Windows (Git Bash/PowerShell)

# ========== PowerShell ==========
ls ~\.ssh

# ========== Git Bash ==========
ls -al ~/.ssh

Common SSH key filenames:

id_rsa.pub - RSA key (older)

id_ecdsa.pub - ECDSA key

id_ed25519.pub - Ed25519 key (recommended)

Generate New SSH Key {#generate-ssh-key}

If you don't have an SSH key or want to create a new one:

Using Ed25519 (Recommended)

Ed25519 is more secure and faster than RSA.

# ========== Generate Ed25519 key ==========
ssh-keygen -t ed25519 -C "your_email@example.com"

# When prompted:
# 1. File location: Press Enter for default (~/.ssh/id_ed25519)
# 2. Passphrase: Enter a secure passphrase (optional but recommended)
# 3. Confirm passphrase

# Output:
# Generating public/private ed25519 key pair.
# Enter file in which to save the key (/home/user/.ssh/id_ed25519):
# Enter passphrase (empty for no passphrase):
# Your identification has been saved in /home/user/.ssh/id_ed25519
# Your public key has been saved in /home/user/.ssh/id_ed25519.pub

Using RSA (Legacy Systems)

If your system doesn't support Ed25519:

# ========== Generate RSA key (4096 bits) ==========
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

# Follow the same prompts as above

Custom Filename

To use a custom filename (useful for multiple accounts):

# ========== Generate with custom filename ==========
ssh-keygen -t ed25519 -C "work@example.com" -f ~/.ssh/id_ed25519_work

# This creates:
# ~/.ssh/id_ed25519_work (private key)
# ~/.ssh/id_ed25519_work.pub (public key)

Add SSH Key to SSH Agent {#add-to-agent}

The SSH agent manages your SSH keys and remembers your passphrase.

Linux/Mac

# ========== Start SSH agent ==========
eval "$(ssh-agent -s)"
# Output: Agent pid 12345

# ========== Add your SSH key ==========
ssh-add ~/.ssh/id_ed25519

# If you used RSA:
ssh-add ~/.ssh/id_rsa

# If you used custom filename:
ssh-add ~/.ssh/id_ed25519_work

# ========== Verify keys are loaded ==========
ssh-add -l
# Output: 256 SHA256:... your_email@example.com (ED25519)

Mac - Add to Keychain

On macOS, you can store the passphrase in Keychain:

# ========== Add key to macOS Keychain ==========
ssh-add --apple-use-keychain ~/.ssh/id_ed25519

# ========== Configure SSH to use Keychain ==========
# Create/edit ~/.ssh/config
cat >> ~/.ssh/config << EOF
Host *
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519
EOF

Windows

# ========== PowerShell (as Administrator) ==========

# Start SSH Agent service
Get-Service ssh-agent | Set-Service -StartupType Automatic
Start-Service ssh-agent

# Add your SSH key
ssh-add ~\.ssh\id_ed25519

# Verify
ssh-add -l

Windows - Add SSH Agent to Startup

# ========== Add to PowerShell profile ==========
# Edit profile
notepad $PROFILE

# Add these lines:
Start-Service ssh-agent
ssh-add ~\.ssh\id_ed25519

Add SSH Key to GitHub {#add-to-github}

Copy Your Public Key

Linux:

# ========== Copy public key to clipboard ==========

# Using xclip (Ubuntu/Debian)
sudo apt-get install xclip
xclip -selection clipboard < ~/.ssh/id_ed25519.pub

# Using xsel
sudo apt-get install xsel
xsel --clipboard < ~/.ssh/id_ed25519.pub

# Or simply cat and copy manually
cat ~/.ssh/id_ed25519.pub

Mac:

# ========== Copy to clipboard ==========
pbcopy < ~/.ssh/id_ed25519.pub

# Or view and copy manually
cat ~/.ssh/id_ed25519.pub

Windows (PowerShell):

# ========== Copy to clipboard ==========
Get-Content ~\.ssh\id_ed25519.pub | Set-Clipboard

# Or view and copy manually
cat ~\.ssh\id_ed25519.pub

Add to GitHub Account

Go to GitHub Settings

- Navigate to: https://github.com/settings/keys - Or: GitHub → Settings → SSH and GPG keys

Click "New SSH key"

Fill in the form:

- Title: Descriptive name (e.g., "Work Laptop - Ubuntu", "Personal MacBook") - Key type: Authentication Key - Key: Paste your public key (starts with ssh-ed25519 or ssh-rsa)

Click "Add SSH key"

Confirm with your GitHub password (if prompted)

Your Public Key Format

Your public key should look like this:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKqP3cr5u2RsJx5xYNe5Nz+DFhn8hBrM9gvwPs/6xdLj your_email@example.com

Or for RSA:

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQC... your_email@example.com

Test SSH Connection {#test-connection}

Verify that your SSH key is working:

# ========== Test connection to GitHub ==========
ssh -T git@github.com

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

# Type 'yes' and press Enter

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

If you see the success message, you're all set! ✅

Verify GitHub's SSH Key Fingerprints

For security, verify GitHub's fingerprints before accepting:

GitHub's official SSH key fingerprints:

SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU (RSA)
SHA256:p2QAMXNIC1TJYWeIOttrVc98/R1BUFWu3/LiyKgUfQM (ECDSA)
SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU (Ed25519)

Source: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/githubs-ssh-key-fingerprints

Clone Repository Using SSH {#clone-repository}

Get SSH Clone URL

Go to the repository on GitHub

Click the green "Code" button

Select "SSH" tab

Copy the URL (format: git@github.com:username/repo.git)

Clone the Repository

# ========== Clone using SSH ==========
git clone git@github.com:username/repository.git

# Example:
git clone git@github.com:torvalds/linux.git

# Clone to specific directory
git clone git@github.com:username/repo.git my-project

# Clone specific branch
git clone -b main git@github.com:username/repo.git

SSH URL Format

git@github.com:username/repository.git

Host: github.com

User: git (always "git" for GitHub)

Username: Your GitHub username

Repository: Repository name

Convert HTTPS to SSH {#convert-https-to-ssh}

If you already cloned a repository using HTTPS, convert it to SSH:

Check Current Remote URL

# ========== View current remote ==========
git remote -v

# Output:
# origin  https://github.com/username/repo.git (fetch)
# origin  https://github.com/username/repo.git (push)

Change to SSH URL

# ========== Change remote URL to SSH ==========
git remote set-url origin git@github.com:username/repo.git

# Verify the change
git remote -v

# Output:
# origin  git@github.com:username/repo.git (fetch)
# origin  git@github.com:username/repo.git (push)

Convert URL Pattern

# ========== HTTPS to SSH conversion ==========

# HTTPS format:
https://github.com/username/repo.git

# SSH format:
git@github.com:username/repo.git

Multiple GitHub Accounts {#multiple-accounts}

Manage multiple GitHub accounts (personal and work) on the same machine.

Step 1: Generate Keys for Each Account

# ========== Personal account key ==========
ssh-keygen -t ed25519 -C "personal@example.com" -f ~/.ssh/id_ed25519_personal

# ========== Work account key ==========
ssh-keygen -t ed25519 -C "work@company.com" -f ~/.ssh/id_ed25519_work

Step 2: Add Keys to SSH Agent

# ========== Add both keys ==========
ssh-add ~/.ssh/id_ed25519_personal
ssh-add ~/.ssh/id_ed25519_work

# Verify
ssh-add -l

Step 3: Configure SSH Config File

Create/edit ~/.ssh/config:

# ========== ~/.ssh/config ==========

# Personal GitHub account
Host github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_personal
    IdentitiesOnly yes

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

Step 4: Add Public Keys to GitHub

Add ~/.ssh/id_ed25519_personal.pub to your personal GitHub account

Add ~/.ssh/id_ed25519_work.pub to your work GitHub account

Step 5: Clone Repositories

# ========== Personal repository ==========
git clone git@github.com:personal-username/repo.git

# ========== Work repository ==========
git clone git@github-work:work-username/repo.git
# Note: Use 'github-work' instead of 'github.com'

Step 6: Configure Git User Per Repository

# ========== In personal repo ==========
cd personal-repo
git config user.name "Personal Name"
git config user.email "personal@example.com"

# ========== In work repo ==========
cd work-repo
git config user.name "Work Name"
git config user.email "work@company.com"

Alternative: Global Git Config with Conditional Includes

~/.gitconfig:

[includeIf "gitdir:~/personal/"]
    path = ~/.gitconfig-personal

[includeIf "gitdir:~/work/"]
    path = ~/.gitconfig-work

~/.gitconfig-personal:

[user]
    name = Personal Name
    email = personal@example.com
    signingkey = ~/.ssh/id_ed25519_personal

[core]
    sshCommand = ssh -i ~/.ssh/id_ed25519_personal

~/.gitconfig-work:

[user]
    name = Work Name
    email = work@company.com
    signingkey = ~/.ssh/id_ed25519_work

[core]
    sshCommand = ssh -i ~/.ssh/id_ed25519_work

Troubleshooting {#troubleshooting}

Permission Denied (publickey)

Error:

Permission denied (publickey).
fatal: Could not read from remote repository.

Solutions:

# ========== 1. Check SSH agent is running ==========
ssh-add -l
# If "Could not open a connection to your authentication agent"
eval "$(ssh-agent -s)"

# ========== 2. Add your SSH key ==========
ssh-add ~/.ssh/id_ed25519

# ========== 3. Check SSH key permissions ==========
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub

# ========== 4. Verify key is added to GitHub ==========
ssh -T git@github.com

# ========== 5. Use verbose mode for debugging ==========
ssh -vT git@github.com

SSH Key Not Working

Check key format:

# ========== View public key ==========
cat ~/.ssh/id_ed25519.pub

# Should start with:
# ssh-ed25519 AAAA...

# If it starts with '-----BEGIN', it's the PRIVATE key!
# NEVER share or upload your private key!

Could Not Resolve Hostname

Error:

ssh: Could not resolve hostname github.com: Name or service not known

Solution:

# ========== Check internet connection ==========
ping github.com

# ========== Check DNS ==========
nslookup github.com

# ========== Try with IP (temporary fix) ==========
ssh -T git@140.82.121.4

Wrong SSH Key Being Used

Force specific key:

# ========== Use specific key for single command ==========
GIT_SSH_COMMAND="ssh -i ~/.ssh/id_ed25519_work" git clone git@github.com:company/repo.git

# ========== Or set for repository ==========
cd repo
git config core.sshCommand "ssh -i ~/.ssh/id_ed25519_work"

Verify Which Key Is Being Used

# ========== Debug SSH connection ==========
ssh -vT git@github.com 2>&1 | grep "identity file"

# Output shows which keys are being tried:
# debug1: identity file /home/user/.ssh/id_ed25519 type 3

SSH Agent Not Persisting

Linux - Add to shell profile:

# ========== Add to ~/.bashrc or ~/.zshrc ==========
if [ -z "$SSH_AUTH_SOCK" ] ; then
  eval "$(ssh-agent -s)"
  ssh-add ~/.ssh/id_ed25519
fi

Windows - Set SSH agent to auto-start:

# ========== PowerShell (Administrator) ==========
Get-Service ssh-agent | Set-Service -StartupType Automatic
Start-Service ssh-agent

Passphrase Required Every Time

Linux/Mac - Add to keychain:

# ========== Mac ==========
ssh-add --apple-use-keychain ~/.ssh/id_ed25519

# ========== Linux (GNOME) ==========
ssh-add ~/.ssh/id_ed25519
# Gnome Keyring will prompt to save passphrase

# ========== Or use keychain utility ==========
sudo apt-get install keychain
# Add to ~/.bashrc:
eval $(keychain --eval --agents ssh id_ed25519)

GitHub Changed Remote URL

Update remote URL:

# ========== Check current remote ==========
git remote -v

# ========== Update to SSH ==========
git remote set-url origin git@github.com:username/repo.git

# ========== Or update HTTPS URL ==========
git remote set-url origin https://github.com/username/repo.git

Best Practices

Security Best Practices

Use Ed25519 keys - More secure and faster than RSA

Use a passphrase - Protects private key if stolen

One key per device - Easy to revoke if device is lost

Never share private keys - Only share .pub files

Regularly rotate keys - Generate new keys periodically

Review authorized keys - Remove old/unused keys from GitHub

File Permissions

Correct SSH file permissions are critical:

# ========== Set correct permissions ==========
chmod 700 ~/.ssh                      # Directory
chmod 600 ~/.ssh/id_ed25519          # Private key
chmod 644 ~/.ssh/id_ed25519.pub      # Public key
chmod 644 ~/.ssh/known_hosts         # Known hosts
chmod 644 ~/.ssh/config              # Config file

Key Management

# ========== List all keys on GitHub ==========
# Go to: https://github.com/settings/keys

# ========== Remove old keys ==========
# Delete keys from devices you no longer use

# ========== Audit key usage ==========
# Check "Last used" date on GitHub

# ========== Backup keys ==========
# Store private keys securely (encrypted backup)
cp -r ~/.ssh ~/Backups/ssh-keys-$(date +%Y%m%d)

Quick Reference

Essential Commands

# ========== SSH Key Management ==========

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

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

# List loaded keys
ssh-add -l

# Remove all keys from agent
ssh-add -D

# Test GitHub connection
ssh -T git@github.com

# ========== Git Commands ==========

# Clone with SSH
git clone git@github.com:username/repo.git

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

# View remotes
git remote -v

# ========== Troubleshooting ==========

# Verbose SSH connection
ssh -vT git@github.com

# Check SSH key permissions
ls -la ~/.ssh

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

Configuration Files

# ========== Important file locations ==========

~/.ssh/                          # SSH directory
~/.ssh/id_ed25519               # Private key (NEVER share)
~/.ssh/id_ed25519.pub           # Public key (add to GitHub)
~/.ssh/config                   # SSH configuration
~/.ssh/known_hosts              # Known host keys
~/.gitconfig                    # Git global config

Additional Resources

Official Documentation

GitHub SSH Docs: https://docs.github.com/en/authentication/connecting-to-github-with-ssh

SSH Keygen Manual: man ssh-keygen

SSH Agent Manual: man ssh-agent

Git Remote Manual: git help remote

Useful Tools

# ========== SSH tools ==========
ssh-keygen          # Generate SSH keys
ssh-add             # Add keys to agent
ssh-agent           # Key management daemon
ssh-copy-id         # Copy key to remote server

# ========== Git tools ==========
git remote          # Manage remotes
git config          # Configure Git
git credential      # Credential management

Related Topics

GPG Keys: For commit signing

Git Credential Manager: Alternative auth method

Personal Access Tokens: HTTPS alternative

Deploy Keys: Repository-specific keys

GitHub CLI: gh auth commands

Summary

Setup Steps:

✅ Generate SSH key: ssh-keygen -t ed25519 -C "email@example.com"

✅ Add to SSH agent: ssh-add ~/.ssh/id_ed25519

✅ Copy public key: cat ~/.ssh/id_ed25519.pub

✅ Add to GitHub: Settings → SSH Keys → New SSH Key

✅ Test connection: ssh -T git@github.com

✅ Clone repository: git clone git@github.com:username/repo.git

Key Points:

🔐 SSH is more secure than HTTPS for GitHub

🔑 Ed25519 keys are recommended over RSA

🛡️ Always use a passphrase for private keys

📱 Use different keys for different devices

⚙️ Configure ~/.ssh/config for multiple accounts

🔍 Test with ssh -T git@github.com before cloning

You're now ready to securely work with GitHub using SSH! 🚀