How to Add an SSH Key to GitHub (Step-by-Step)

Secure Shell (SSH) keys provide a safe and convenient way to connect to GitHub without entering a username and password each time. Instead of relying on HTTPS authentication, SSH uses a pair of cryptographic keys to verify identity and establish a secure connection between a local machine and GitHub’s servers. For developers working regularly with repositories, understanding how to configure SSH access is an essential skill.

TLDR: To add an SSH key to GitHub, first generate an SSH key pair on a local machine using the terminal. Next, copy the public key and add it to the GitHub account settings under SSH and GPG keys. Finally, test the connection using an SSH command to confirm everything works correctly. Once configured, Git operations can be performed without repeatedly entering login credentials.

Why Use SSH with GitHub?

Using SSH offers several clear advantages over HTTPS authentication:

• Enhanced security: SSH uses encrypted key pairs rather than plain credentials.
• Convenience: No need to enter a password with every push or pull.
• Automation-friendly: Ideal for scripts and deployment workflows.
• Widely supported: Compatible with macOS, Windows, and Linux systems.

For developers managing multiple repositories or collaborating across teams, SSH simplifies workflow management and improves efficiency.

Step 1: Check for Existing SSH Keys

Before generating a new key, it is helpful to determine whether one already exists on the system. On macOS or Linux, this can be done by opening the terminal and running:

ls -al ~/.ssh

On Windows, the same command can be run in PowerShell or Git Bash.

If files such as id_rsa, id_ed25519, or similar pairs (public and private keys) appear, an SSH key may already exist. If no keys are present, a new one must be generated.

Step 2: Generate a New SSH Key

If no suitable SSH key is found, generate one using the following command:

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

The ed25519 algorithm is recommended for modern systems due to its strong security and performance.

After running the command:

1. The system will prompt for a file location. Press Enter to accept the default location.
2. Next, create a secure passphrase. While optional, it is strongly recommended for added protection.

Once completed, two files will be created in the .ssh directory:

• Private key (e.g., id_ed25519) – Keep this confidential.
• Public key (e.g., id_ed25519.pub) – This will be uploaded to GitHub.

Step 3: Start the SSH Agent

To ensure the system can use the key securely, the SSH agent must be running. Start it with:

eval "$(ssh-agent -s)"

Next, add the generated key to the agent:

ssh-add ~/.ssh/id_ed25519

This step enables the system to manage the private key without repeatedly entering credentials.

Step 4: Copy the Public Key

The public key must now be copied so it can be added to GitHub.

On macOS:

pbcopy < ~/.ssh/id_ed25519.pub

On Linux:

cat ~/.ssh/id_ed25519.pub

Then manually copy the displayed content.

On Windows (Git Bash):

clip < ~/.ssh/id_ed25519.pub

The key should begin with ssh-ed25519 and end with the provided email address.

Step 5: Add the SSH Key to GitHub

Once copied, the key must be added to the GitHub account:

1. Log in to GitHub.
2. Click the profile photo in the top-right corner.
3. Select Settings.
4. Navigate to SSH and GPG keys.
5. Click New SSH key.
6. Add a descriptive title (e.g., “Work Laptop” or “Home PC”).
7. Paste the copied key into the Key field.
8. Click Add SSH key.

If prompted, confirm the GitHub password.

Image not found in postmeta

Step 6: Test the SSH Connection

To verify the setup, run the following command:

ssh -T git@github.com

If successful, the system will display a message such as:

Hi username! You've successfully authenticated, but GitHub does not provide shell access.

This confirmation means GitHub recognizes the device and SSH authentication is working properly.

Step 7: Update Repository Remote URLs (If Needed)

If repositories were previously cloned using HTTPS, their remote URLs must be updated to use SSH.

Check the current remote with:

git remote -v

If it shows an HTTPS URL (e.g., https://github.com/username/repo.git), change it with:

git remote set-url origin git@github.com:username/repo.git

This ensures Git operations use SSH instead of HTTPS moving forward.

Troubleshooting Common Issues

While the process is generally straightforward, a few issues may arise:

• Permission denied (publickey): Ensure the correct key is added and the SSH agent is running.
• Key already exists: Consider generating a new key with a unique name.
• Multiple accounts conflict: Configure separate SSH config entries for each account.
• Firewall restrictions: Verify that port 22 is not blocked.

In most cases, rechecking each setup step resolves the issue quickly.

Best Practices for Managing SSH Keys

To maintain secure access, developers should follow these recommendations:

• Use a passphrase to add an extra layer of security.
• Do not share private keys.
• Rotate keys periodically if working in high-security environments.
• Remove unused keys from GitHub accounts.
• Create separate keys for work and personal systems.

Following these practices ensures long-term account safety and better access control.

Conclusion

Adding an SSH key to GitHub enhances both security and efficiency. By generating a secure key pair, registering the public key with GitHub, and verifying the connection, developers can streamline their workflow and safeguard repository access. The setup process takes only a few minutes, yet significantly improves daily interactions with GitHub repositories. Once configured, SSH becomes a reliable and frictionless authentication method for all Git operations.

Frequently Asked Questions (FAQ)

• 1. Is SSH better than HTTPS for GitHub?
  Yes. SSH eliminates repeated credential entry and offers strong encryption, making it ideal for regular developers and automation workflows.

• 2. Can multiple SSH keys be added to one GitHub account?
  Yes. GitHub allows multiple SSH keys, which is useful when accessing the account from several devices.

• 3. What happens if the private key is lost?
  A new SSH key pair must be generated and the new public key added to GitHub. The old key should be removed from account settings.

• 4. Is a passphrase required when generating an SSH key?
  No, but it is strongly recommended for enhanced security.

• 5. Can SSH keys be used for GitHub Enterprise?
  Yes. The process is nearly identical, though the domain used in commands may differ.

• 6. How can SSH keys be removed from GitHub?
  Navigate to Settings > SSH and GPG keys, locate the key, and click Delete.

• 7. What is the difference between public and private SSH keys?
  The public key is shared with GitHub to verify identity, while the private key remains secure on the user’s local machine.