MervCodes

Tech Reviews From A Programmer

How to Set Up SSH Keys for GitHub (Mac, Linux and Windows)

1 min read

How to Set Up SSH Keys for GitHub (Mac, Linux and Windows)

If you've ever grown tired of typing your GitHub username and password every time you push code, SSH keys are the solution. Once configured, Git operations authenticate silently in the background — no prompts, no friction, just fast and secure communication between your machine and GitHub.

This guide walks you through the entire process on macOS, Linux, and Windows, from generating your key pair to verifying the connection.

What Is an SSH Key and Why Use It?

SSH (Secure Shell) uses asymmetric cryptography: a private key that stays on your machine and a public key that you share with GitHub. When you connect, GitHub encrypts a challenge with your public key, and only your private key can decrypt it. No password is ever transmitted over the network.

Advantages over HTTPS authentication:

  • No need for personal access tokens or passwords
  • More secure: private key never leaves your machine
  • Works seamlessly in scripts and CI/CD pipelines
  • Faster authentication for frequent pushers

Prerequisites

  • Git installed on your system
  • A GitHub account
  • Terminal access (Terminal on Mac/Linux, Git Bash or PowerShell on Windows)

Step 1 — Check for Existing SSH Keys

Before generating a new key, check whether you already have one.

Mac / Linux:

ls -al ~/.ssh

Windows (Git Bash or PowerShell):

ls ~/.ssh

Look for files named:

  • id_ed25519 and id_ed25519.pub
  • id_rsa and id_rsa.pub

If these exist and you want to reuse them, skip to Step 3. If they don't exist — or you want a fresh key — continue to Step 2.

Step 2 — Generate a New SSH Key

The recommended algorithm today is Ed25519. It is faster and more secure than the older RSA-4096. Use RSA only if you need compatibility with very old systems.

Mac and Linux

Open your terminal and run:

ssh-keygen -t ed25519 -C "[email protected]"

Replace [email protected] with the email address linked to your GitHub account. The -C flag adds a label so you can identify the key later.

You'll see:

Generating public/private ed25519 key pair.
Enter file in which to save the key (/home/you/.ssh/id_ed25519):

Press Enter to accept the default location. Then set a passphrase:

Enter passphrase (empty for no passphrase):

A passphrase is strongly recommended. It encrypts your private key on disk so that even if someone steals the file, they cannot use it without the passphrase. You won't need to type it on every Git operation — the SSH agent handles that.

Windows

Option A: Git Bash (recommended)

Git Bash ships with ssh-keygen. Open Git Bash and run the same command:

ssh-keygen -t ed25519 -C "[email protected]"

Follow the same prompts as above. Keys are saved to C:\Users\YourName\.ssh\.

Option B: PowerShell (Windows 10/11 with OpenSSH)

Windows 10 1809 and later include OpenSSH. Open PowerShell as administrator and check if it's available:

Get-WindowsCapability -Online | Where-Object Name -like 'OpenSSH*'

If not installed:

Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0

Then generate the key:

ssh-keygen -t ed25519 -C "[email protected]"

Step 3 — Add Your Key to the SSH Agent

The SSH agent holds your decrypted private key in memory so you only need to enter your passphrase once per session.

Mac

Start the agent and add your key:

eval "$(ssh-agent -s)"
ssh-add --apple-use-keychain ~/.ssh/id_ed25519

The --apple-use-keychain flag stores the passphrase in macOS Keychain so it persists across reboots. On macOS 12 Monterey and earlier, the flag is -K instead.

To make this permanent, add the following to ~/.ssh/config:

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

Linux

Start the agent and add the key:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

To persist the key across sessions, add the ssh-add command to your shell profile (~/.bashrc, ~/.zshrc, etc.), or configure your desktop environment's keyring (GNOME Keyring, KWallet) to manage SSH keys automatically.

Windows (Git Bash)

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

Windows (PowerShell with OpenSSH):

Enable the OpenSSH Authentication Agent service so it starts automatically:

Set-Service ssh-agent -StartupType Automatic
Start-Service ssh-agent
ssh-add $env:USERPROFILE\.ssh\id_ed25519

Step 4 — Add Your Public Key to GitHub

Copy your public key to the clipboard. Never share the private key (the file without .pub).

Mac:

pbcopy < ~/.ssh/id_ed25519.pub

Linux:

xclip -selection clipboard < ~/.ssh/id_ed25519.pub
# or if xclip isn't available:
cat ~/.ssh/id_ed25519.pub

Windows (Git Bash):

clip < ~/.ssh/id_ed25519.pub

Windows (PowerShell):

Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub | Set-Clipboard

Now add the key to GitHub:

  1. Go to GitHub → Settings → SSH and GPG keys
  2. Click New SSH key
  3. Give it a descriptive title (e.g., MacBook Pro 2025 or Work Linux Desktop)
  4. Set Key type to Authentication Key
  5. Paste your public key into the Key field
  6. Click Add SSH key

Step 5 — Test the Connection

Verify that everything is configured correctly:

ssh -T [email protected]

You'll likely see a prompt about host authenticity on the first connection:

The authenticity of host 'github.com (140.82.121.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. GitHub's official ED25519 fingerprint is SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU — confirm it matches before accepting.

A successful connection shows:

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

Step 6 — Clone Repositories Using SSH

With SSH configured, always use the SSH clone URL (not HTTPS):

# SSH (correct)
git clone [email protected]:username/repository.git

# HTTPS (requires token-based auth)
git clone https://github.com/username/repository.git

If you have an existing repository cloned via HTTPS and want to switch it to SSH:

git remote set-url origin [email protected]:username/repository.git

Verify the change:

git remote -v

Managing Multiple GitHub Accounts

If you work with multiple GitHub accounts (personal and work), create separate keys and configure ~/.ssh/config:

# Personal account
Host github-personal
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_personal

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

Then clone using the custom host alias:

git clone git@github-personal:personaluser/repo.git
git clone git@github-work:workorg/repo.git

FAQ

Q: What's the difference between Ed25519 and RSA?

Ed25519 uses elliptic curve cryptography and produces shorter, faster keys with equivalent or better security than RSA-4096. Use Ed25519 unless you're working with legacy systems that don't support it.

Q: Do I need one SSH key per computer or per GitHub account?

One key per computer is the standard approach. Generate a separate key on each machine and add each one to GitHub. This way you can revoke access from a specific machine without affecting others.

Q: Is a passphrase required?

No, but it's strongly recommended. Without a passphrase, anyone who gets access to your private key file can authenticate as you. The SSH agent means you only type the passphrase once per session, so the security benefit far outweighs the minor inconvenience.

Q: My SSH test fails with "Permission denied (publickey)". What do I do?

Run ssh -vT [email protected] to get verbose output. Common causes include: the key not being added to the SSH agent (ssh-add), the wrong key on file in GitHub, or a firewall blocking port 22. For the firewall case, try SSH over HTTPS port 443 by adding Port 443 and Hostname ssh.github.com to your ~/.ssh/config for the github.com host.

Q: Can I use the same SSH key for multiple Git hosting services (GitLab, Bitbucket)?

Yes. Copy the same public key to each service. You can also generate service-specific keys and use ~/.ssh/config to route each host to the correct key — useful if you want to revoke access to one service independently.

Q: How do I rotate or revoke a key?

Delete the key from GitHub under Settings → SSH and GPG keys, then delete the local key files (~/.ssh/id_ed25519 and ~/.ssh/id_ed25519.pub) and generate a new pair. There is no built-in expiry mechanism for SSH keys, so periodic rotation is a good security hygiene practice.

Q: Will SSH keys work in GitHub Actions or CI/CD?

Yes. For CI/CD, you typically add the private key as a secret environment variable and configure the SSH agent in your pipeline steps. GitHub Actions also offers its own GITHUB_TOKEN for repository operations, which is often simpler for pure automation use cases.

SSH key authentication is one of those one-time setup tasks that pays ongoing dividends. Once it's in place, the authentication friction of daily Git work disappears entirely — and your credentials stay more secure than any password-based method. Set it up once per machine and forget about it.

← Back to all posts