How to use an SSH key with GitHub

SSH keys provide secure authentication for GitHub repositories without requiring your username and password each time you push or pull code. The key acts as a unique digital credential tied to your machine.

You will generate an SSH key pair on your local device and add the public portion to your GitHub account. Once configured, you can interact with your repositories from the command line without entering credentials.

Generate an SSH key pair

You will create a new SSH key pair on your local machine. This generates two files: a private key that stays on your device and a public key that you share with GitHub.

First, check whether you already have an SSH key:

ssh-add -l

If this command lists an existing key, you can use that key with GitHub. If no key exists, follow these steps to create one:

1. Open your terminal application.
   On macOS or Linux, use the built-in terminal. On Windows, use PowerShell or Windows Terminal.
2. Generate the key pair.
   Run the command below, replacing name@domain.tld with your email address. This creates a 4096-bit RSA key, which provides strong security for GitHub authentication.

ssh-keygen -t rsa -b 4096 -C "name@domain.tld"

3. Accept the default file location.
   Press Enter when prompted for a file location. This saves your key to ~/.ssh/id_rsa, which is the standard location SSH clients check automatically.
4. Set a passphrase.
   Enter a secure passphrase when prompted and press Enter. This adds an extra layer of protection to your private key. You will need to enter this passphrase when using the key.
5. Retrieve your public key.
   Run the command below to display your public key. This is the portion you will add to GitHub.

cat ~/.ssh/id_rsa.pub

Copy the entire output, starting with ssh-rsa and ending with your email address. Never share your private key file (id_rsa) with anyone or commit it to a repository.

Add your public key to GitHub

You will now add your public key to your GitHub account. This allows GitHub to recognise your machine when you connect via SSH.

1. Log in to GitHub.
   Open your browser and navigate to github.com. Sign in to your account.
2. Open your account settings.
   Click your avatar in the top right corner and select Settings from the dropdown menu.
3. Navigate to SSH keys.
   In the left sidebar, click SSH and GPG keys. This page displays all SSH keys associated with your account.
4. Add a new key.
   Click the New SSH key button in the top right corner.
5. Enter key details.
   In the Title field, enter a descriptive name that identifies this machine, such as “Work Laptop” or “Home Desktop”. Paste your copied public key into the Key field.
6. Save the key.
   Click Add SSH key. GitHub may prompt you to confirm your password. Your machine is now authorised to access your repositories via SSH.

Test your connection by running this command in your terminal:

ssh -T git@github.com

If successful, you will see a message confirming authentication. You can now clone repositories using SSH URLs and push changes without entering your GitHub credentials.

Wrapping up

Your machine now authenticates with GitHub using SSH keys. You generated a key pair, added the public key to your GitHub account and tested the connection. You can now work with repositories from the command line without entering your username and password.

Review our guide on connecting and using SSH for more information about SSH authentication. If you manage repositories on your hosting account, learn how to set up Git version control in cPanel.