Configure Git and SSH Authentication Keys

Why Use SSH for Git?

When interacting with remote Git repositories on GitHub, GitLab, or self-hosted servers, using SSH (Secure Shell) keys offers substantial benefits over standard HTTPS username and personal access tokens:

• Cryptographic Security: Public-key cryptography replaces passwords with 256-bit elliptic curve key pairs that cannot be brute-forced.
• Persistent Frictionless Authentication: Once your private key is loaded into the operating system SSH agent, you can clone, pull, and push without entering credentials.
• Isolated Permissions: Each workstation or development server receives its own unique SSH key pair. If a laptop is lost, its key can be revoked immediately without resetting your primary password.

Step 1: Checking for Existing SSH Keys

Open Windows Terminal, PowerShell, or Git Bash and inspect your local .ssh directory:

ls ~/.ssh

Look for filenames like id_ed25519 and id_ed25519.pub. If you already have these files, you can skip to Step 3 to register the public key.

Step 2: Generating a Modern Ed25519 Key Pair

The Ed25519 elliptic curve algorithm is modern, faster, and cryptographically superior to legacy RSA 2048/4096-bit keys.

Run the following command, substituting your actual email address:

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

1. File Location Prompt: Press Enter to accept the default file location (~/.ssh/id_ed25519).
2. Passphrase Prompt: Enter a secure passphrase for key encryption, or press Enter twice for a passwordless key on a secure personal machine.

This generates two files in ~/.ssh/:

• id_ed25519 — Private key (Never share, publish, or commit this file).
• id_ed25519.pub — Public key (This is uploaded to GitHub, GitLab, or servers).

Step 3: Starting the SSH Agent and Adding Your Key

On Windows, ensure the ssh-agent Windows service is running:

# In PowerShell as Administrator:
Get-Service ssh-agent | Set-Service -StartupType Automatic
Start-Service ssh-agent

# Add your private key to the agent:
ssh-add ~/.ssh/id_ed25519

Step 4: Adding the Public Key to GitHub or GitLab

Copy the contents of your public key to the clipboard:

# On Windows PowerShell:
Get-Content ~/.ssh/id_ed25519.pub | Set-Clipboard

1. Log into your account on GitHub.com.
2. Navigate to Settings > SSH and GPG keys.
3. Click New SSH key.
4. Give it a descriptive title (e.g., Workstation-Win11).
5. Set the Key type to Authentication Key.
6. Paste your copied key into the Key field and click Add SSH key.

Step 5: Testing the SSH Connection

Run the SSH authentication diagnostic:

ssh -T git@github.com

You will see a fingerprint verification prompt on the first connection:

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

Type yes and press Enter. You should receive the standard success message:

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

Step 6: Switching Existing Repositories from HTTPS to SSH

If you cloned an existing project via HTTPS, switch its remote URL to SSH:

# Check current remote URL:
git remote -v

# Switch to SSH URL:
git remote set-url origin git@github.com:username/repository.git