How to set up SSH key authentication (GitHub + Linux)

SSH key authentication replaces password logins with a cryptographic key pair: a private key kept secret on your client machine, and a public key placed on the server (or GitHub). This guide walks through generating an Ed25519 SSH key pair, configuring the ssh-agent, uploading the public key to GitHub, and authorizing key-based login on a Linux server — all using open, verifiable sources.

About SSH key authentication

SSH (Secure Shell) uses public key cryptography for authenticating users. The protocol never sends your private key over the network; instead, it proves possession of the private key by signing a challenge. This eliminates password brute-force and phishing risks.

A typical SSH key pair consists of:

• Private key (~/.ssh/id_ed25519): Never shared; decrypts authentication challenges.
• Public key (~/.ssh/id_ed25519.pub): Shared with servers/GitHub; verifies signatures.

When you attempt to connect, the server encrypts a nonce with your public key; only your private key can decrypt it to prove identity.

Why Ed25519? Modern Ed25519 keys offer equivalent security to 3072-bit RSA with faster performance and smaller size. GitHub requires Ed25519 or RSA with SHA-2 signatures for keys uploaded after March 15, 2022.

Step 1 — Check for existing SSH keys

Before generating a new key, check whether you already have SSH keys in ~/.ssh/:

ls -la ~/.ssh/

Common filenames: id_rsa, id_ecdsa, id_ed25519. If you see both a private key (no extension) and a .pub file, a key pair already exists. Back up or reuse existing keys if preferred.

Step 2 — Generate a new Ed25519 key pair

Run ssh-keygen to create a new key pair. Replace your_email@example.com with your GitHub or account email.

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

You'll see prompts:

1. File to save the key: Press Enter to accept the default location (~/.ssh/id_ed25519).
2. Passphrase (optional but recommended): Enter a secure passphrase to encrypt your private key file. You'll need to enter this whenever the key is used unless loaded into ssh-agent.
3. Repeat passphrase: Confirm the passphrase.

The output shows the key fingerprint and randomart image — a visual representation of your key.

Legacy systems note: If your system doesn't support Ed25519 (very old OpenSSH), use ssh-keygen -t rsa -b 4096 -C "your_email@example.com" instead. Ensure the RSA key uses SHA-2 signatures (required by GitHub for newer keys).

Step 3 — Start ssh-agent and add your key

The ssh-agent is a background program that holds your private key decrypted in memory, so you don't enter the passphrase for every connection.

Start the agent and add your key:

# Start the agent in the background
eval "$(ssh-agent -s)"
# Add your private key to the agent
ssh-add ~/.ssh/id_ed25519

If you set a passphrase, you'll be prompted to enter it once. The agent will now supply your key for SSH authentication until you log out or kill the agent.

To make this persistent across sessions, add the eval "$(ssh-agent -s)" line to your shell profile (~/.bashrc, ~/.zshrc, etc.).

Step 4 — Copy the public key to GitHub

To authenticate with GitHub over SSH, add your public key to your GitHub account.

1. Copy the public key to your clipboard:

   # macOS
   pbcopy < ~/.ssh/id_ed25519.pub
   
   # Linux (requires xclip or wl-clipboard)
   xclip -selection clipboard < ~/.ssh/id_ed25519.pub
   # or
   wl-clipboard < ~/.ssh/id_ed25519.pub
   
   # WSL2
   clip.exe < ~/.ssh/id_ed25519.pub
   

2. In GitHub:

   • Click your profile picture → Settings.
   • In the left sidebar, click SSH and GPG keys.
   • Click New SSH key or Add SSH key.
   • Paste the key into the Key field.
   • Give it a descriptive title (e.g., "Personal Laptop Ed25519").
   • Select Key type as Authentication.
   • Click Add SSH key.

Verify: After adding, GitHub shows the key fingerprint and the date added.

Step 5 — Set up key-based login on a Linux server

To use SSH keys for server login (instead of passwords), copy your public key to the server's ~/.ssh/authorized_keys file.

Option A — Using ssh-copy-id (recommended)

If ssh-copy-id is available (installed with OpenSSH), run:

ssh-copy-id -i ~/.ssh/id_ed25519.pub user@your_server_ip

Replace user with your username and your_server_ip with the server's address or hostname. You'll be prompted for the user's password one last time. The tool appends your public key to ~/.ssh/authorized_keys on the server.

Option B — Manual copy

If ssh-copy-id isn't available, manually append the key:

cat ~/.ssh/id_ed25519.pub | ssh user@your_server_ip 'mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 700 ~/.ssh && chmod 600 ~/.ssh/authorized_keys'

Again, replace user@your_server_ip with your target. You'll be prompted for the password.

Set correct permissions (critical)

On the server, ensure the .ssh directory and files have restrictive permissions:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

Incorrect permissions cause SSH to ignore the key file for security reasons.

Step 6 — Test your SSH connection

Verify that authentication works without a password prompt.

Test GitHub SSH

ssh -T git@github.com

You should see:

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

If it's the first connection, GitHub shows its host key fingerprint. Verify it matches GitHub's published fingerprint, then type yes.

Test Linux server SSH

ssh user@your_server_ip

If you set a passphrase on the key, you'll be prompted to enter it (unless the key is loaded in ssh-agent). Otherwise, you should log in directly.

Step 7 — Optional: Add key to ssh-agent automatically

To avoid running ssh-add every session, add your key to the agent automatically.

Add these lines to your shell profile (~/.bashrc, ~/.zshrc):

# Start ssh-agent if not running
if [ -z "$SSH_AUTH_SOCK" ]; then
   eval "$(ssh-agent -s)"
   ssh-add ~/.ssh/id_ed25519
fi

This starts the agent on demand and loads your key.

Common mistakes to avoid

• Wrong permissions: ~/.ssh must be 700, authorized_keys must be 600. SSH ignores insecure permissions.
• Forgotten passphrase: If you set a passphrase and don't load the key into ssh-agent, you'll be prompted for it on every connection.
• Mixing key types: Ensure the public key you upload matches the private key you're using (Ed25519 vs RSA).
• Server not allowing pubkey auth: Check /etc/ssh/sshd_config on the server for PubkeyAuthentication yes and restart sshd after changes.
• Agent not running: If you see Agent admitted failure to sign using the key, the key isn't loaded in ssh-agent. Run ssh-add ~/.ssh/id_ed25519.

FAQ

How do I use different SSH keys for different accounts?

Use Host aliases in ~/.ssh/config. Example:

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

# Work account (different key)
Host github-work
   HostName github.com
   User git
   IdentityFile ~/.ssh/id_ed25519_work
   IdentitiesOnly yes

Then use git@github-work:user/repo.git for work repos.

Can I use the same SSH key for GitHub and server login?

Yes. The same public key can be placed in multiple places: your GitHub account, server authorized_keys, or any service accepting SSH keys. However, for high-security separation, use different key pairs.

What if I lose my private key?

Generate a new key pair and repeat the setup process. Immediately remove the lost/public key from all services (GitHub, servers) to prevent unauthorized access.

Should I encrypt my private key with a passphrase?

Yes, if the key is stored on a laptop or shared machine. A passphrase encrypts the private key file so theft of the laptop doesn't grant immediate access. On a secure, isolated workstation you may skip it, but a passphrase is recommended.

How do I rotate SSH keys?

Generate a new key pair, add the new public key to all services, verify login works, then remove the old public key from GitHub and server authorized_keys files.

Summary

SSH key authentication provides secure, passwordless login for GitHub and Linux servers. By generating an Ed25519 key pair, using ssh-agent, and copying the public key to the right places, you replace vulnerable passwords with strong cryptography. Always verify connections, maintain proper file permissions, and rotate keys periodically for best security.

With these steps, you can authenticate to GitHub push/pull and SSH into servers without typing a password — while keeping your private key secret.