How to Set Up SSH Keys for GitHub on Windows, macOS and Linux

SSH keys let Git authenticate with GitHub without asking you to enter account credentials for every Git operation. You create a public and private key pair on your computer, add the public key to your GitHub account, and keep the private key protected on your device. This guide walks through the complete setup on Windows, macOS and Linux, then shows how to test the connection and use an SSH remote in an existing repository.
Quick overview: Check for an existing key, generate an Ed25519 key if needed, load the private key into your SSH agent, and add the public key under GitHub Settings → SSH and GPG keys. Then test the connection with:
ssh -T git@github.com
OpenSSH and Git are free tools; no paid software is required for these steps.
What is an SSH key, and why use it with GitHub?
SSH (Secure Shell) is a protocol that creates an encrypted connection between your computer and a remote server. GitHub supports SSH authentication for Git operations such as cloning, fetching and pushing repositories.
An SSH key pair contains two related files:
- Private key: stays on your computer. Protect it like a password and never upload it to GitHub, paste it into a website, or commit it to a repository.
- Public key: can be shared with GitHub. It is the file whose name ends in .pub.
When you connect, your SSH client proves that it holds the private key corresponding to the public key registered with GitHub. The private key itself is not sent to GitHub. SSH authentication does not give you extra repository permissions; your GitHub account still needs access to the repository.
Before you create a new SSH key
First check whether your computer already has a key you can use. Creating another key unnecessarily can make it harder to know which identity Git is using.
On macOS, Linux or Git Bash, open a terminal and run:
ls -al ~/.ssh
Look for a matching private and public pair, such as id_ed25519 and id_ed25519.pub. On Windows PowerShell, you can inspect the same folder with:
Get-ChildItem "$env:USERPROFILE\.ssh"
If you already have a suitable key, you may be able to add its public key to GitHub and load the private key into your SSH agent. If you are unsure who else uses the key or what it can access, create a separate key for this computer instead.
Step 1: Generate an Ed25519 SSH key
GitHub’s current instructions use Ed25519 for a new key on supported systems. Open Terminal, PowerShell or Git Bash and run the command below. Replace the example email with the email address associated with your GitHub account:
ssh-keygen -t ed25519 -C "your_email@example.com"
When prompted for a file location, press Enter to use the default path if it is available. If a key with that name already exists, do not overwrite it unless you are certain it is no longer needed. Choose a distinct name such as id_ed25519_github_personal instead.
When prompted, enter a strong passphrase. A passphrase adds protection if someone obtains the private-key file. The SSH agent can remember the unlocked key during your session so you do not have to type the passphrase for every Git operation.
For an older system that does not support Ed25519, GitHub documents RSA with a 4096-bit key as an alternative:
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
Step 2: Add the private key to the SSH agent
The SSH agent keeps an unlocked key available to SSH clients. The commands differ slightly by operating system.
Windows 10 and Windows 11
Windows 10 support note: Windows 10 Home and Pro, version 22H2, reached end of support on 14 October 2025. The OpenSSH commands below may still run, but standard editions no longer receive regular security updates. Prefer a currently supported Windows release, and check Microsoft’s Windows 10 lifecycle notice for the status of your specific edition; LTSC editions can have separate dates.
Open PowerShell and check whether the OpenSSH client is available:
Get-Command ssh, ssh-keygen
ssh -V
If the commands are not found, open Settings → System → Optional features and check for OpenSSH Client. If it is missing, install the client feature from Optional features. You can also install it from an elevated PowerShell window with Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0. You need the OpenSSH Client for GitHub authentication; you do not need to install the OpenSSH Server just to use GitHub.
To start the Windows SSH agent, open PowerShell as Administrator and run:
Get-Service -Name ssh-agent | Set-Service -StartupType Manual
Start-Service ssh-agent
Close the elevated window. In a normal PowerShell window, add your private key to the agent:
ssh-add "$env:USERPROFILE\.ssh\id_ed25519"
If you saved the key under a different filename, replace id_ed25519 with that name. Windows and Git for Windows can use different OpenSSH executables; if the agent works in PowerShell but Git Bash keeps asking for the passphrase, check which ssh.exe Git is using before changing global Git settings.
macOS
Open Terminal and start the agent if it is not already running:
eval "$(ssh-agent -s)"
For the standard Apple OpenSSH client, add the key and store its passphrase in the macOS Keychain:
ssh-add --apple-use-keychain ~/.ssh/id_ed25519
GitHub’s macOS instructions also use a ~/.ssh/config entry so the key is loaded for GitHub connections:
Host github.com
AddKeysToAgent yes
UseKeychain yes
IdentityFile ~/.ssh/id_ed25519
If you chose not to set a passphrase, omit UseKeychain. If your SSH client reports that UseKeychain is an unknown option, follow GitHub’s note about IgnoreUnknown UseKeychain or use the SSH client supplied with macOS. If ~/.ssh/config already contains a Host github.com section, merge these settings into it instead of creating a duplicate section.
Linux
Open your terminal and start an agent in the current shell if your desktop environment has not already started one:
eval "$(ssh-agent -s)"
Then add your private key:
ssh-add ~/.ssh/id_ed25519
If you use a custom filename, provide its full path to ssh-add. Some Linux desktop environments already manage an SSH agent; if the command reports that an agent is unavailable or one is already running, check your distribution’s session and keyring configuration rather than starting multiple agents blindly.
Step 3: Add your public key to GitHub
Copy the contents of the public-key file. Do not copy the private-key file.
On Windows PowerShell:
Get-Content "$env:USERPROFILE\.ssh\id_ed25519.pub" | Set-Clipboard
On macOS:
pbcopy < ~/.ssh/id_ed25519.pub
On Linux, print the public key and copy the complete single line:
cat ~/.ssh/id_ed25519.pub
Now sign in to GitHub in your browser:
- Open your profile menu and select Settings.
- Under Access, open SSH and GPG keys.
- Select New SSH key.
- Enter a clear title, such as Personal laptop – Windows.
- For key type, select Authentication Key.
- Paste the contents of the .pub file and select Add SSH key.
- Complete any account confirmation that GitHub requests.
If your organization uses SAML single sign-on, you may also need to authorize the SSH key for that organization. Adding a key to your personal account does not automatically grant access to every organization or repository.
Step 4: Test your GitHub SSH connection
Return to your terminal and run:
ssh -T git@github.com
The first time you connect, SSH may ask you to confirm GitHub’s host identity. Compare the displayed fingerprint with the fingerprints on GitHub’s official SSH key fingerprints page before accepting it. Do not approve an unfamiliar fingerprint just to make the warning disappear.
A successful test displays a message similar to:
Hi USERNAME! You’ve successfully authenticated, but GitHub does not provide shell access.
This is expected. GitHub’s documentation notes that the remote command should exit with code 1. When the message above includes your username and says that authentication succeeded, the key was accepted. GitHub uses SSH for Git operations and does not provide an interactive shell.
Step 5: Use the SSH URL for a Git repository
When you clone a repository, choose the SSH URL from the repository’s Code menu. It looks like this:
git clone git@github.com:OWNER/REPOSITORY.git
Replace OWNER and REPOSITORY with the actual account or organization and repository name. For a repository you already cloned using HTTPS, inspect the current remote first:
git remote -v
To change the origin remote to SSH, use:
git remote set-url origin git@github.com:OWNER/REPOSITORY.git
git remote -v
Changing the remote URL does not change the repository’s files or commit history. It changes how Git connects to the remote. If HTTPS already works for your workflow, you can keep using it; SSH is an alternative, not a requirement.
Fix common GitHub SSH errors
Permission denied (publickey)
GitHub did not accept the key offered by your SSH client. Check that you added the correct public key to the correct GitHub account, that the private key is present on this computer, and that the agent has loaded it:
ssh-add -l
If the list is empty, add the key again with ssh-add. If several keys are loaded, use an SSH configuration entry with IdentityFile and IdentitiesOnly yes to select the intended key.
Could not open a connection to your authentication agent
The SSH agent may not be running in the current session. Start it using the instructions for your operating system, then run ssh-add again. On Windows, check the ssh-agent service. On macOS and Linux, check whether your terminal session already has an agent configured.
SSH asks for a passphrase every time
The key may not be loaded into the agent, or Git may be using a different SSH executable from the one connected to the agent. Confirm the key with ssh-add -l, then check the SSH client Git uses. On Windows, Git for Windows and the built-in Windows OpenSSH client can use separate agent environments.
Port 22 is blocked by a firewall
If your network blocks the standard SSH port, GitHub documents an SSH option over port 443. Test it with:
ssh -T -p 443 git@ssh.github.com
If that succeeds, add this entry to ~/.ssh/config:
Host github.com
Hostname ssh.github.com
Port 443
User git
The host for this connection is ssh.github.com, not github.com. Verify the host fingerprint when prompted. Proxy servers or strict network policies may still prevent the connection.
Host key verification failed
SSH has detected that the host key does not match the entry stored in your known_hosts file. Do not delete the entry automatically. First check GitHub’s published fingerprints and confirm whether the host key has legitimately changed. If the saved entry is stale, update only the affected entry using a trusted, verified fingerprint.
SSH key safety checklist
- Keep the private key file on your device. Share only the public .pub key with GitHub.
- Use a strong passphrase and an SSH agent or operating-system keychain where appropriate.
- Use a separate key for each device or clearly defined environment when practical.
- Never commit private keys, passphrases or copied credentials to a repository.
- Remove a lost, exposed or unrecognized key from GitHub promptly, then create and register a replacement.
- Review the SSH keys listed in GitHub Settings periodically and remove keys you no longer use.
- For automated server deployments, evaluate repository-scoped deploy keys or a GitHub App instead of placing a personal private key on a server.
If you download Git, an editor or another developer tool, use the publisher’s official source. When the publisher provides a checksum, you can also follow our guide to verify a SHA-256 checksum on Windows, macOS and Linux.
Frequently asked questions
Do I need an SSH key to use GitHub?
No. GitHub also supports HTTPS authentication. SSH is useful if you prefer key-based authentication for Git operations and want to avoid entering credentials for each connection.
Can I use the same SSH key on more than one computer?
You can technically copy a private key, but a separate key for each device is easier to audit and revoke. If one laptop is lost, you can remove that device’s key without replacing the key used by every other computer.
Should I upload id_ed25519 or id_ed25519.pub?
Upload or paste only id_ed25519.pub. The file without .pub is the private key and must remain protected on your computer.
Why does GitHub say it does not provide shell access?
That message is normal after a successful SSH authentication test. GitHub accepts the key for Git operations but does not open a general-purpose shell session.
Can I use SSH from a work or college network?
It depends on the network’s firewall and proxy rules. If port 22 is blocked, GitHub documents an SSH-over-port-443 option. Follow your organisation’s network and security policies before changing connection settings.
Conclusion
Setting up SSH keys for GitHub is a one-time process for each computer: check for an existing key, create a protected key pair, load the private key into the SSH agent, register the public key with GitHub and test the connection. Once it works, use the repository’s SSH URL when cloning or update the remote URL of an existing project. Keep the private key private, verify host fingerprints and remove keys you no longer trust.
Official references
- GitHub: Check for existing SSH keys
- GitHub: Generate a new SSH key and add it to the SSH agent
- GitHub: Add an SSH key to your account
- GitHub: Test your SSH connection
- GitHub: Troubleshoot SSH
- GitHub: SSH key fingerprints
- GitHub: Use SSH over port 443
- GitHub: Authorize an SSH key for SAML single sign-on
- Microsoft Learn: OpenSSH key-based authentication on Windows
- Microsoft Learn: Install and get started with OpenSSH on Windows
- Microsoft Learn: Install OpenSSH Client features on Windows
- Git documentation: Manage remote repositories





