To use SSHSSH A secure way to type commands on a server from your own computer, as if you were sitting at it. More about SSH → keys with GitHub, you create a key pair on your own computer, paste the public half into your GitHub settings, and tell Git to use an SSH address for your repositories. This guide is for anyone who pushes code to GitHub from Windows, macOS or Linux, including from a web server that pulls a site’s code.
Run ssh-keygen -t ed25519 -C “you@example.com” and accept the default file location. Copy the contents of ~/.ssh/id_ed25519.pub, then in GitHub go to Settings, SSH and GPG keys, New SSH key and paste it in as an Authentication Key. Test with ssh -T git@github.com: a message saying you have successfully authenticated means it works.
Why use an SSH key for GitHub
GitHub does not accept your account password when Git pushes or pulls code. You need either a personal access token over HTTPSHTTPS The secure version of the web, shown by the padlock. Everything sent between you and the site is scrambled so nobody in between can read or change it. More about HTTPS → or an SSH key. An SSH key is set up once per computer and then works silently.
A key pair is two files. The private key (id_ed25519) stays on your computer and must never be shared or uploaded anywhere. The public key (id_ed25519.pub) is safe to give out, and that is the half GitHub stores. When Git connects, GitHub checks that your computer holds the private key that matches. If SSH or key pairs are new to you, What is SSH? explains the idea in more depth.
You can use the same key for GitHub and for logging in to your own servers, but many people make one key per computer and add it to every service that computer needs.
Step 1: check for an existing key
You may already have a key. Open a terminal (Terminal on macOS and Linux; PowerShell or Git Bash on Windows) and list your SSH folder:
ls ~/.ssh
If you see id_ed25519 and id_ed25519.pub, you already have a key and can skip to step 3. If the folder does not exist or holds only known_hosts, carry on.
Step 2: generate a new key
Run this, using the email address on your GitHub account. The -C part is only a label (a comment) inside the key so you can recognise it later:
ssh-keygen -t ed25519 -C "you@example.com"
-t ed25519 picks the Ed25519 key type, which is short, fast and the type GitHub recommends. Then answer the prompts:
- Enter file in which to save the key: press Enter to accept the default,
~/.ssh/id_ed25519. On Windows this isC:\Users\exampleco\.ssh\id_ed25519. - Enter passphrase: type a passphrase and press Enter, then type it again. A passphrase encrypts the private key, so a stolen laptop does not mean a stolen GitHub account. Step 5 shows how to avoid typing it every time.
Success looks like a message that your identification and public key have been saved, followed by a key fingerprint starting SHA256: and a small block of ASCII art.
If you need to connect from a very old system that does not understand Ed25519, use ssh-keygen -t rsa -b 4096 -C "you@example.com" instead. The files are then called id_rsa and id_rsa.pub.
Step 3: add the public key to GitHub
First copy the public key. Make sure the file name ends in .pub.
| System | Command to copy the public key |
|---|---|
| macOS | pbcopy < ~/.ssh/id_ed25519.pub |
| Windows (Git Bash) | clip < ~/.ssh/id_ed25519.pub |
| Windows (PowerShell) | Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub then select and copy the line |
| Linux | cat ~/.ssh/id_ed25519.pub then select and copy the line |
The key is one long line starting ssh-ed25519 and ending with your email label. Then, in GitHub:
- Click your profile picture in the top right and choose Settings.
- In the Access section of the sidebar, click SSH and GPG keys.
- Click New SSH key.
- Give it a Title that names the computer, such as “Work laptop” or “web serverWeb server The program that answers visitors’ browsers and sends them your website. Also used for the computer it runs on. More about Web server → example.com”.
- Leave Key type set to Authentication Key.
- Paste the key into the Key box and click Add SSH key. GitHub may ask you to confirm your password or two-factor code.
Never paste the private key (the file without .pub) into GitHub or anywhere else. If you ever do, delete that key from GitHub at once and generate a new pair.
Step 4: test the connection
ssh -T git@github.com
The first time, SSH shows GitHub’s host key fingerprint and asks whether to continue. GitHub’s Ed25519 fingerprint is SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU. If it matches, type yes. SSH records it in ~/.ssh/known_hosts and will warn you if it ever changes.
Success looks like this:
Hi exampleco! You've successfully authenticated, but GitHub does not provide shell access.
The second half is normal. GitHub lets Git in over SSH but never gives you a command line on its servers.
Step 5: stop typing the passphrase every time
An SSH agent is a small background program that holds your unlocked key in memory, so you type the passphrase once per session rather than on every push.
macOS
Create or edit ~/.ssh/config and add:
Host github.com
AddKeysToAgent yes
UseKeychain yes
IdentityFile ~/.ssh/id_ed25519
Then add the key once, saving the passphrase in your macOS keychain:
ssh-add --apple-use-keychain ~/.ssh/id_ed25519
Windows
Windows includes an OpenSSH agent service that is switched off by default. Open PowerShell as administrator and run:
Get-Service ssh-agent | Set-Service -StartupType Automatic
Start-Service ssh-agent
Then, in a normal PowerShell window:
ssh-add $env:USERPROFILE\.ssh\id_ed25519
Linux
Most desktop Linux systems start an agent when you log in. Add the key with:
ssh-add ~/.ssh/id_ed25519
On a server with no desktop, start an agent for the current session first with eval "$(ssh-agent -s)".
Step 6: use SSH addresses for your repositories
A key only helps if Git uses an SSH address. On a repository’s GitHub page, click Code, choose the SSH tab and copy the address. It looks like git@github.com:exampleco/example-site.git.
To clone a new repository:
git clone git@github.com:exampleco/example-site.git
To switch an existing repository that was cloned over HTTPS, go into its folder and run:
git remote set-url origin git@github.com:exampleco/example-site.git
git remote -v
The second command should now show the git@github.com: address for both fetch and push.
Common problems
| Symptom | Cause | Fix |
|---|---|---|
Permission denied (publickey) | GitHub does not have the public key, or SSH is offering a different key | Check the key is listed under SSH and GPG keys. Run ssh -vT git@github.com and look for which key file is offered. |
| Git still asks for a username and password | The repository remote is an HTTPS address | Run git remote set-url with the SSH address as in step 6. |
Key is already in use when adding it | The same key is attached to another GitHub account or as a deploy key | Generate a separate key for this account, or remove it from the other place first. |
| Connection times out on port 22 | A firewall or office network blocks the SSH port | Use GitHub’s SSH over port 443: see the config below. |
Bad configuration option: usekeychain | UseKeychain is a macOS-only option | Remove it on Linux and Windows, or add IgnoreUnknown UseKeychain above it. |
Error connecting to agent on Windows | The ssh-agent service is not running | Run the administrator commands in step 5. |
If portPort A numbered door on a server. Each service listens behind its own door: web pages on 443, email on others, remote login on 22. More about Port → 22 is blocked, add this to ~/.ssh/config. GitHub accepts SSH on port 443 at the host name ssh.github.com:
Host github.com
Hostname ssh.github.com
Port 443
User git
Test again with ssh -T git@github.com.
Official documentation
- GitHub Docs: Generating a new SSH key and adding it to the ssh-agent
- GitHub Docs: Testing your SSH connection
- GitHub Docs: Using SSH over the HTTPS port
Related
- How to set up SSH keys: use the same kind of key to log in to your own server without a password.
- How to connect to a server with SSH: the basics of connecting and the host key prompt.
- What is WSL? How to run Linux on Windows: a full Linux terminal on Windows, which keeps its own separate SSH keys.
- Common network ports and what they are used for: why port 22 is sometimes blocked and what 443 is for.
Something out of date? Software changes. If a step no longer works, tell us and we will check it and update the page.



