❯shell.recipes

Set up an SSH key for GitHub

Generate an Ed25519 SSH key, load it into ssh-agent, add it to your GitHub account, test the connection, and switch a repo from HTTPS to SSH.

7 steps⏱ 10 minBeginnerLinux · macOS · Windows✓ Verified 4 Nov 2026

Showing commands for This recipe doesn't cover this OS yet.

With an SSH key, git push and git pull work without typing a password or token each time. GitHub recommends Ed25519 keys.

Check for an existing key

Linux · macOSbash
ls -al ~/.ssh
WindowsPowerShell
Get-ChildItem -Force $HOME\.ssh

Nothing to run on for this part.

If you already see id_ed25519 and id_ed25519.pub, you can reuse them and skip to step 3. If the folder doesn’t exist, that’s fine, the next step creates it.

Generate a new key

All systemsbash
ssh-keygen -t ed25519 -C "you@example.com"
All systemsExpected output
Generating public/private ed25519 key pair.
Enter file in which to save the key (/home/you/.ssh/id_ed25519):
Enter passphrase (empty for no passphrase):

Nothing to run on for this part.

Press Enter to accept the default file. Then choose a passphrase. It protects the key if your laptop is stolen, and the agent in the next step means you won’t have to retype it often.

Very old system without Ed25519 support? Use ssh-keygen -t rsa -b 4096 -C "you@example.com" instead.

Load the key into ssh-agent

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

# Create ~/.ssh/config (if it doesn't exist) so macOS keeps the key in your Keychain
touch ~/.ssh/config
cat >> ~/.ssh/config <<'EOF'
Host github.com
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519
EOF

# Use Apple's built-in ssh-add, not a Homebrew/MacPorts one
ssh-add --apple-use-keychain ~/.ssh/id_ed25519
WindowsPowerShell
# 1) In an *Administrator* PowerShell window: enable and start the agent
Get-Service -Name ssh-agent | Set-Service -StartupType Manual
Start-Service ssh-agent

# 2) Back in a normal (non-admin) window: add your key
ssh-add $HOME\.ssh\id_ed25519
Linux · macOSExpected output
Identity added: /home/you/.ssh/id_ed25519 (you@example.com)

Nothing to run on for this part.

macOS: no passphrase on your key? Leave out the UseKeychain yes line. If you get Bad configuration option: usekeychain, add IgnoreUnknown UseKeychain under Host github.com.

Copy your public key

Copy the .pub file only. Never share the private key (the file without .pub).

Linuxbash
cat ~/.ssh/id_ed25519.pub
# Select and copy the whole line that starts with ssh-ed25519
macOSzsh
pbcopy < ~/.ssh/id_ed25519.pub
WindowsPowerShell
Get-Content $HOME\.ssh\id_ed25519.pub | Set-Clipboard

Nothing to run on for this part.

Add the key to your GitHub account

In the browser: GitHub → profile photo → Settings → SSH and GPG keys → New SSH key. Name it My laptop, keep type Authentication Key, paste the key, then Add SSH key.

Or from the terminal with the GitHub CLI (gh auth login first):

Linux · macOSbash
gh ssh-key add ~/.ssh/id_ed25519.pub --title "My laptop"
WindowsPowerShell
gh ssh-key add $HOME\.ssh\id_ed25519.pub --title "My laptop"

Nothing to run on for this part.

Test the connection

All systemsbash
ssh -T git@github.com
All systemsExpected output
The authenticity of host 'github.com (IP ADDRESS)' can't be established.
ED25519 key fingerprint is SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU.
Are you sure you want to continue connecting (yes/no)? yes
Hi octocat! You've successfully authenticated, but GitHub does not provide shell access.

Nothing to run on for this part.

Before typing yes, check that the fingerprint matches GitHub’s published fingerprints.

Use SSH for your repositories

Clone new repos with the SSH URL, or switch an existing HTTPS clone over:

All systemsbash
# New clone
git clone git@github.com:octocat/my-project.git

# Existing clone: run inside the repo folder
git remote set-url origin git@github.com:octocat/my-project.git
git remote -v
All systemsExpected output
origin  git@github.com:octocat/my-project.git (fetch)
origin  git@github.com:octocat/my-project.git (push)

Nothing to run on for this part.

Troubleshooting

Permission denied (publickey): the agent doesn’t have your key. Run ssh-add -l to list loaded keys, then repeat step 3.

Windows: Git keeps asking for the passphrase: Git for Windows may be using its bundled ssh.exe instead of Windows OpenSSH. Point Git at the system one:

WindowsPowerShell
git config --global core.sshCommand "C:/Windows/System32/OpenSSH/ssh.exe"

Nothing to run on for this part.

macOS: asked for the passphrase after every reboot: check that ~/.ssh/config has the UseKeychain yes block from step 3.

Sources

Commands checked against these official sources on 4 Nov 2026. Found something out of date? Open an issue.

  1. Generating a new SSH key and adding it to the ssh-agent · GitHub Docs
  2. Adding a new SSH key to your GitHub account · GitHub Docs
  3. Testing your SSH connection · GitHub Docs
  4. GitHub's SSH key fingerprints · GitHub Docs