About SSH keys

You can use SSH to perform Git operations in repositories on GitHub.com. For more information, see “About SSH.”

If you have an existing SSH key, you can use the key to authenticate Git operations over SSH.

Checking for existing SSH keys

Before you generate a new SSH key, you should check your local machine for existing keys.

Note: GitHub improved security by dropping older, insecure key types on March 15, 2022.

As of that date, DSA keys (ssh-dss) are no longer supported. You cannot add new DSA keys to your personal account on GitHub.com.

RSA keys (ssh-rsa) with a valid_after before November 2, 2021, may continue to use any signature algorithm. RSA keys generated after that date must use an SHA-2 signature algorithm. Some older clients may need to be upgraded in order to use SHA-2 signatures.

  1. Open Git Bash.
  2. Enter ls -al ~/.ssh to see if existing SSH keys are present.
    $ ls -al ~/.ssh
    # Lists the files in your .ssh directory, if they exist
  3. Check the directory listing to see if you already have a public SSH key. By default, the filenames of supported public keys for GitHub are one of the following.
    • id_rsa.pub
    • id_ecdsa.pub
    • id_ed25519.pub

    Tip: If you receive an error that ~/.ssh doesn’t exist, you do not have an existing SSH key pair in the default location. You can create a new SSH key pair in the next step.

  4. Either generate a new SSH key or upload an existing key.
    • If you don’t have a supported public and private key pair, or don’t wish to use any that are available, generate a new SSH key.
    • If you see an existing public and private key pair listed (for example, id_rsa.pub and id_rsa) that you would like to use to connect to GitHub, you can add the key to the ssh-agent.For more information about the generation of a new SSH key or the addition of an existing key to the ssh-agent, see “Generating a new SSH key and adding it to the ssh-agent.”

 

Generating a new SSH key

You can generate a new SSH key on your local machine. After you create the key, you can add the key to your account on GitHub.com to enable authentication for Git operations over SSH.

Note: GitHub improved security by dropping older, insecure key types on March 15, 2022.

As of that date, DSA keys (ssh-dss) are no longer supported. You cannot add new DSA keys to your personal account on GitHub.com.

RSA keys (ssh-rsa) with a valid_after before November 2, 2021, may continue to use any signature algorithm. RSA keys generated after that date must use an SHA-2 signature algorithm. Some older clients may need to be upgraded in order to use SHA-2 signatures.

  1. Open Git Bash.
  2. Paste the text below, substituting it in your GitHub email address.
    $ ssh-keygen -t ed25519 -C "your_email@example.com"

    Note: If you are using a legacy system that doesn’t support the Ed25519 algorithm, use:

    $ ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

    This creates a new SSH key, using the provided email as a label.

    > Generating public/private ALGORITHM key pair.

    When you’re prompted to “Enter a file in which to save the key”, you can press Enter to accept the default file location. Please note that if you created SSH keys previously, ssh-keygen may ask you to rewrite another key, in which case we recommend making a custom-named SSH key. To do so, type the default file location and replace id_ssh_keyname with your custom key name.

    > Enter a file in which to save the key (/c/Users/YOU/.ssh/id_ALGORITHM):[Press enter]
  3. At the prompt, type a secure passphrase. For more information, see “Working with SSH key passphrases.”
    > Enter passphrase (empty for no passphrase): [Type a passphrase]
    > Enter same passphrase again: [Type passphrase again]

Adding your SSH key to the ssh-agent

Before adding a new SSH key to the ssh-agent to manage your keys, you should have checked for existing SSH keys and generated a new SSH key.

If you have GitHub Desktop installed, you can use it to clone repositories and not deal with SSH keys.

  1. Ensure the ssh-agent is running. You can use the “Auto-launching the ssh-agent” instructions in “Working with SSH key passphrases“, or start it manually:
    # start the ssh-agent in the background
    $ eval "$(ssh-agent -s)"
    > Agent pid 59566
  2. Add your SSH private key to the ssh-agent. If you created your key with a different name, or if you are adding an existing key that has another name, replace id_ed25519 in the command with the name of your private key file.
    $ ssh-add ~/.ssh/id_ed25519
  3. Add the SSH key to your account on GitHub. For more information, see “Adding a new SSH key to your GitHub account.”

Adding a new SSH key to your account

After adding a new SSH authentication key to your account on GitHub.com, you can reconfigure any local repositories to use SSH. For more information, see “Switching remote URLs from HTTPS to SSH.”

Note: GitHub improved security by dropping older, insecure key types on March 15, 2022.

As of that date, DSA keys (ssh-dss) are no longer supported. You cannot add new DSA keys to your personal account on GitHub.com.

RSA keys (ssh-rsa) with a valid_after before November 2, 2021, may continue to use any signature algorithm. RSA keys generated after that date must use an SHA-2 signature algorithm. Some older clients may need to be upgraded in order to use SHA-2 signatures.

  1. Copy the SSH public key to your clipboard.If your SSH public key file has a different name than the example code, modify the filename to match your current setup. When copying your key, don’t add any new lines or whitespace.
    $ clip < ~/.ssh/id_ed25519.pub
      # Copies the contents of the id_ed25519.pub file to your clipboard

    Tip: If clip isn’t working, you can locate the hidden .ssh folder, open the file in your favourite text editor, and copy it to your clipboard.

  2. In the upper-right corner of any page, click your profile photo, then click Settings.Settings icon in the user bar
  3. In the “Access” section of the sidebar, click  SSH and GPG keys.
  4. Click New SSH key or Add SSH key.SSH Key button
  5. In the “Title” field, add a descriptive label for the new key. For example, if you’re using a personal laptop, you might call this key “Personal laptop”.
  6. Select the type of key, either authentication or signing. For more information about commit signing, see “About commit signature verification.”
  7. Paste your key into the “Key” field.The key field
  8. Click Add SSH key.The Add key button
  9. If prompted, confirm access to your account on GitHub. For more information, see “Sudo mode.”
Tags:

Leave a Reply