Configure SSH Keys for GitHub on Any OS

SSH keys let Git authenticate with GitHub without asking you to enter your account password for every Git operation. Setting them up involves more than generating a key: you also need to add its public half to GitHub, make the private key available to an SSH agent, and test the connection. This guide walks through those steps on Windows, macOS, and Linux, and explains how to protect your private key.

Key takeaways

Generate an Ed25519 key unless your environment does not support it; use a passphrase to protect the private key.
Add the public key (.pub) to your GitHub account. Never upload or share the private key.
Use an SSH agent to handle the key during Git operations, then test with ssh -T git@github.com.
Check that your repository uses an SSH remote, not an HTTPS remote, if Git still asks for HTTPS credentials.

Before you begin

Install Git and make sure you can sign in to GitHub in a browser. You will add a key to the GitHub account that should have access to your repositories.

Check whether you already have SSH keys before creating another one. In a terminal, run:

ls -la ~/.ssh

On Windows PowerShell, use:

Get-ChildItem $env:USERPROFILE\.ssh

If you find an existing key, do not overwrite it unless you understand what uses it. You can keep separate keys for different accounts or devices and select the appropriate one through SSH configuration.

Generate an SSH key

Ed25519 is a suitable default for current OpenSSH installations. Use the email address associated with your GitHub account as a comment; the comment helps identify the key but does not determine access.

Run this command in macOS Terminal, Linux, Windows PowerShell, or Git Bash:

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

When prompted for a file, press Enter to use the default path (~/.ssh/id_ed25519 on macOS and Linux, or your Windows user profile's .ssh directory). If a key already exists at that path, stop and choose a different filename or decide deliberately whether to replace it.

When prompted, set a strong passphrase. The passphrase encrypts the private key on disk; the SSH agent can remember it for you after you enter it. Do not put the passphrase in a script or share it. If Ed25519 is unavailable in an older environment, GitHub documents RSA as an alternative; use a sufficiently strong key size, such as 4096 bits.

The command creates two files:

id_ed25519 — the private key. Keep it on your device and protect it.
id_ed25519.pub — the public key. This is the one you add to GitHub.

Add the public key to GitHub

Copy the contents of the .pub file. Do not copy the file without .pub or paste the private key into GitHub.

Use the command for your platform:

macOS:

pbcopy < ~/.ssh/id_ed25519.pub

Windows PowerShell:

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

Linux:

cat ~/.ssh/id_ed25519.pub

On Linux, copy the printed line manually, or use a clipboard utility available in your desktop environment. The public key is usually a single line beginning with ssh-ed25519.

In GitHub, open Settings → SSH and GPG keys → New SSH key. Give the key a recognizable title, such as the device name, leave the key type as Authentication Key, paste the public key, and save it. A key added to your personal account grants authentication as that account; only add it to accounts you are authorized to use.

Start an SSH agent and add the key

An SSH agent holds an unlocked key for use by SSH clients, so you do not have to type its passphrase for every connection. The exact setup depends on the operating system and shell.

macOS

Add the key to the macOS keychain-backed agent:

ssh-add --apple-use-keychain ~/.ssh/id_ed25519

If you use a custom key filename, substitute that path. To have SSH select the key and use the keychain, create or edit ~/.ssh/config:

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

Save the file with permissions that restrict access to your user:

chmod 600 ~/.ssh/config

Linux

Many desktop environments start an agent for you. If your current terminal does not have an agent available, start one in that shell and add the key:

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

This starts an agent for the current shell session; it does not configure every Linux distribution or desktop session to start an agent automatically. Follow your distribution or desktop environment's guidance for persistent agent setup rather than adding repeated agent-start commands to shell startup files without checking how your session is managed.

Windows

Windows supports more than one OpenSSH setup. In PowerShell, you can use the Windows OpenSSH Authentication Agent service. If the service is not configured, open PowerShell as an administrator to enable automatic startup, then start it:

Get-Service ssh-agent | Set-Service -StartupType Automatic
Start-Service ssh-agent

Add the key from a regular PowerShell window:

ssh-add $env:USERPROFILE\.ssh\id_ed25519

If you use Git Bash instead, start an agent in that shell if one is not already available, then add the key:

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

Choose the agent approach that matches the SSH client Git is using. Mixing Windows OpenSSH and Git for Windows installations can lead to different clients seeing different agent keys.

Test GitHub authentication

Run:

ssh -T git@github.com

The first connection may ask you to confirm GitHub's host key. Verify the fingerprint against GitHub's current documentation before accepting it; do not approve an unexpected fingerprint without checking. A successful authentication displays a message identifying your GitHub username and notes that GitHub does not provide shell access. That message is expected: SSH authentication is working even though the command does not open an interactive shell.

If you see Permission denied (publickey), check that the public key was added to the correct GitHub account, that the matching private key is loaded into the agent, and that SSH is selecting the right key. You can inspect the agent's loaded keys with:

ssh-add -l

If it reports that no identities are available, add your key again with ssh-add. For more detail while troubleshooting, run ssh -vT git@github.com; review the output locally and avoid sharing it if it includes private paths or other information you do not want to disclose.

Make sure your repository uses SSH

SSH authentication only applies when the repository's remote URL uses SSH. Check the current remote:

git remote -v

An SSH remote looks like git@github.com:OWNER/REPOSITORY.git. An HTTPS remote begins with https://github.com/. If you want to switch an existing repository to SSH, use the SSH URL shown on that repository's GitHub page:

git remote set-url origin git@github.com:OWNER/REPOSITORY.git

Replace OWNER/REPOSITORY with the correct account or organization and repository. Then confirm the change with git remote -v and try a Git operation you are authorized to perform.

Common mistakes and fixes

Adding the private key to GitHub: Add only the .pub file's contents. If you exposed the private key, remove the corresponding public key from GitHub and replace the key pair.
Using the wrong account: A key must be added to the GitHub account that needs access. Check the username in the successful ssh -T response.
Expecting SSH to work with an HTTPS remote: Change the repository remote to its SSH URL if you want Git to use your SSH key.
Assuming the agent is persistent everywhere: Agents may be tied to a shell, desktop session, or operating-system service. Confirm which SSH client Git invokes and add the key to the corresponding agent.
Overwriting an existing key: Check the .ssh directory first. Choose a new filename when you need a separate key.
Treating a successful test as repository authorization: Authentication identifies your account; repository permissions still determine whether you can read or write a particular repository.

Keep your SSH key secure

Treat the private key like a password. Keep it on a device you control, protect it with a passphrase, and do not commit it to a repository, attach it to a support request, or send it in chat or email. The public key is intended to be shared with GitHub, but it should still be added only to accounts where you want that device to authenticate.

Use a separate key for each device when practical. If a device is lost, retired, or no longer trusted, remove its key from GitHub settings. Keep your operating system and OpenSSH installation updated, and avoid granting account access to keys you cannot identify. If you manage multiple GitHub accounts, use distinct key files and explicit SSH configuration so one account's key is not accidentally used for another.

Conclusion

To configure SSH keys for GitHub, generate a key pair, add only the public key to your GitHub account, load the private key into the appropriate SSH agent, and verify authentication with ssh -T git@github.com. Finally, make sure each repository uses an SSH remote. Protecting the private key and removing keys you no longer trust are essential parts of the setup.

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