A broken SSH connection to a GitHub repository usually stems from expired keys, incorrect permissions on the local identity file, or changes in the remote server's host key verification. By regenerating the key pair, updating the
~/.ssh/config file with the correct user and port settings, and verifying that the public key is present in your GitHub account settings, you can restore secure access without needing to switch protocols.
Verify Your Local Key Permissions
The most common reason for an SSH key suddenly failing after working for years is a change in file permissions. The OpenSSH client is extremely strict about security; if your private key file is readable by other users, it will refuse to use it entirely. You must ensure that the permission bits on your private key (typically located at
~/.ssh/id_rsa or
~/.ssh/id_ed25519) are set to 600. This means only the owner can read and write the file.
To check your current permissions, run the following command in your terminal:
ls -l ~/.ssh/id_rsa
If the output shows something like
-rw-r--r--, the permissions are too open. You need to restrict them immediately using the chmod command:
chmod 600 ~/.ssh/id_rsa
This step alone resolves the majority of "permission denied" errors that appear unexpectedly. If you have multiple keys, ensure that each one has these restrictive permissions. Additionally, check the directory permissions for the
.ssh folder itself, which should be 700. Run
chmod 700 ~/.ssh if necessary. This ensures that no other user on the system can list or access your cryptographic identities.
Check for Expired or Revoked Keys
GitHub does not automatically expire SSH keys based on age, but organizational policies may enforce rotation. If your organization uses Single Sign-On (SSO) or specific security groups, your key might have been revoked by an administrator. Log into your GitHub account and navigate to Settings > SSH and GPG keys. Review the list of active keys. If the key associated with your local machine is missing, you must generate a new one.
Generate a new Ed25519 key, which is more secure than the older RSA standard:
ssh-keygen -t ed25519 -C "[email protected]"
When prompted, press Enter to accept the default location. Do not set a passphrase if you want seamless automation, though this reduces security slightly. Once generated, add the public key to your clipboard:
cat ~/.ssh/id_ed25519.pub | clip
On Linux or macOS, use
pbcopy instead of
clip. Then, paste this key into the GitHub web interface under New SSH Key. Save the changes. This ensures that the server recognizes the latest credential you possess.
Update Your SSH Configuration File
Sometimes the issue lies not in the key itself, but in how the SSH client routes connections to GitHub. Modern GitHub configurations require specific host aliases. Edit or create the
~/.ssh/config file on your local machine. Add the following block to ensure that all connections to GitHub use the correct protocol and key:
Host github.com
HostName ssh.github.com
User git
Port 443
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yes
Using port 443 is crucial if you are behind a corporate firewall that blocks standard SSH port 22. The
IdentitiesOnly yes flag forces SSH to use only the specified key, preventing it from trying every key in your agent and hitting a timeout or rejection. After saving this file, test the connection:
ssh -T [email protected]
You should see a message saying "Hi username! You've successfully authenticated." If this fails, refer to our guide on
troubleshooting SSH connection delays to diagnose network-level bottlenecks.
Clear Stale Host Keys
GitHub occasionally rotates its server host keys for security updates. If your local
known_hosts file contains an old fingerprint, SSH will reject the connection as a potential man-in-the-middle attack. Look for warnings in your terminal output mentioning "REMOTE HOST IDENTIFICATION HAS CHANGED."
To fix this, remove the stale entry for GitHub. Run:
ssh-keygen -R github.com
This command deletes the old record. The next time you connect, SSH will ask you to confirm the new fingerprint. Type "yes" to accept it. This process refreshes the trust relationship between your machine and the GitHub servers. Be cautious when accepting new host keys, as they verify the server's identity.
Restart the SSH Agent
Your local SSH agent caches loaded keys. If you recently changed keys or permissions, the agent might still be holding onto the old, invalid state. Restarting the agent clears this cache. On Linux, you can kill the existing agent and start a new one:
eval $(ssh-agent -s)
ssh-add ~/.ssh/id_ed25519
On macOS, the keychain handles this differently, but you can reset it via System Preferences > Users and Groups > Login Items, or by running
ssh-add -K ~/.ssh/id_ed25519. Ensure that the key is listed when you run
ssh-add -l. If it is not there, the agent cannot present it during authentication.
For users experiencing broader connectivity issues, such as timeouts or routing problems, consult
unable to connect Ubuntu 20.04 to Windows for insights on network stack configurations that might interfere with SSH traffic.
Frequently Asked Questions
Why does my SSH key work locally but fail on CI/CD pipelines?
CI/CD environments often lack a persistent SSH agent or have restricted file systems. You must ensure the private key is stored securely in the pipeline's secret variables and added to the agent dynamically before any git commands run. Always use
ssh-add within the build script steps.
Can I use a password-protected SSH key with GitHub?
Yes, GitHub supports password-protected keys. However, automated scripts will fail because they cannot input the passphrase interactively. For non-interactive environments, you must use a key without a passphrase or configure an SSH agent to cache the unlocked key temporarily.
What should I do if I get a 'host key verification failed' error?
This error indicates a mismatch between the known host key and the server's current key. Remove the old entry from
~/.ssh/known_hosts using
ssh-keygen -R github.com and reconnect. Accept the new fingerprint when prompted to establish a fresh trust link.
Does GitHub support Ed25519 keys?
Yes, GitHub fully supports Ed25519 keys, which are generally preferred over RSA due to their smaller size and stronger security profile. Generate them using
ssh-keygen -t ed25519 and add the public portion to your account settings.
How do I check if my SSH key is being used correctly?
Use the verbose flag during connection attempts:
ssh -vT [email protected]. Look for lines indicating "Offering public key" and "Authentication succeeded." If you see "No more authentication methods to try," your key is not being offered or is rejected by the server.