# How to use an SSH key with GitHub Using an SSH key with GitHub enables passwordless access to Git repositories. Instead of identifying a user by username and password, your machine is authenticated via the SSH key. ## What is an SSH key? The [Secure Shell](https://www.ionos.com/digitalguide/server/tools/ssh-secure-shell/ "SSH: Secure Shell") (SSH) is the **standard tool for encrypted access to remote systems**. SSH allows you to log into a server from your home machine. Git uses SSH as a transfer protocol and allows read and write access to remote repositories. An encrypted connection is used to enable **authentication of the machine** and to ensure that the transmitted data cannot be falsified. Without this, it would be possible for unknown parties to make arbitrary changes to repositories. GitHub via SSH uses [asymmetric encryption](https://www.ionos.com/digitalguide/server/security/public-key-encryption/ "Public key encryption") as a cryptographic method. First, a **pair of private and public keys is created**. This is also referred to as a “public / private key pair”. The private key remains on the user’s own computer. The public key is shared with third parties, e.g., GitHub. If you use an SSH key to access GitHub repositories, you don’t need to enter a password. In general, passwordless logins are considered more secure because **a password can be picked up on by keyloggers or trojans**. Instead of a person knowing the password, a machine is authenticated on which the private key is stored. Using GitHub via SSH is extremely convenient. Once it’s set up, the SSH key allows permanent access to GitHub without further intervention. Other **protocols and services** also benefit from [SSH keys for an encrypted network connection](https://www.ionos.com/digitalguide/server/security/using-ssh-keys-for-your-network-connection/ "Using SSH keys for your network connection"). In addition to Git with SSH, the secure SFTP protocol can be used to exchange files with servers without the need for further configuration. Connecting to Git repositories is usually done **from the command line**. If an SSH key has been set up, a push to a custom repository can be performed without any problems: ```none cd ./folder-with-git-repo/ git push ``` Besides the command line application, **GUI applications also benefit from an established SSH key**. Modern FTP programs support the SSH File Transfer Protocol ([SFTP](https://www.ionos.com/digitalguide/server/know-how/sftp-ssh-file-transfer-protocol/ "SFTP (SSH File Transfer Protocol)")). This is based on SSH and uses existing SSH keys. ## How do you use SSH keys with GitHub? To access your GitHub account with an SSH key, you deposit the public key with GitHub. The private key remains on your own computer. Your machine is authenticated to GitHub by **comparing the key data**. This allows write access to your own repositories. This method also works with [alternatives to GitHub](https://www.ionos.com/digitalguide/websites/web-development/github-alternatives/ "GitHub alternatives") like Gitlab or Bitbucket. As convenient as SSH keys are, you must exercise caution when using them. **Do not share your private key under any circumstances**. The private key may allow another party to impersonate you. A third party could log into a server or modify code in repositories in your name. ### Requirements for using GitHub with an SSH key We’re assuming here that you **work in a Linux-like environment**. This includes Linux/Unix, macOS, as well as Windows with [WSL2](https://www.ionos.com/digitalguide/server/know-how/wsl2-explained/ "WSL2 explained") installed. In addition, the following conditions must be met: - Git has been installed - SSH has been installed - A GitHub account has been created First, let’s check if the local requirements are met. With the following command, we **test if Git and SSH are installed**. Unless you get a “git not found” or “ssh not found” error message, both are present: ```none which git ssh ``` [![Image: Testing the installation of Git and SSH](https://www.ionos.com/digitalguide/fileadmin/_processed_/a/9/csm_testing-the-installation-of-git-and-ssh_ed689de038.webp "Testing the installation of Git and SSH")](https://www.ionos.com/digitalguide/fileadmin/DigitalGuide/Screenshots_2022/testing-the-installation-of-git-and-ssh.png) We have Git and SSH installed on our system. For example, we are looking for a non-existent command “unknown”. Furthermore, we create the .ssh directory in the user folder if it doesn’t already exist: ```none mkdir -vp ~/.ssh/ ``` We’ll explain below how to **create and register an SSH key to use GitHub**. Once this step is complete, we’ll show you how to deposit the public SSH key with GitHub and explain how to access Git repositories using SSH: 1. Create SSH key pair on your own system 2. Deposit public SSH key with GitHub 3. Access GitHub repository with SSH key ### Create and register an SSH key on your own system As a first step, we’ll **create a public / private SSH key pair on our local system**. Copy the commands used for this in the exact same order and run them from your command line. We follow the [official documentation](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent "Documentation from GitHub") from GitHub here. The **procedure changes from time to time** so, [to fix SSH errors](https://www.ionos.com/digitalguide/server/know-how/fixing-ssh-errors/ "Fixing SSH Errors"), it can’t hurt to look there. First, we start the **SSH key generator to create a public / private key pair for GitHub**. We use the ssh keygen command, which is present by default as part of the OpenSSH installation on the system: We call up ssh keygen from the command line and are presented with three options: - Option -f followed by path and name of the new key - Option -t followed by the name of the algorithm, in this case ed25519 - Option -C followed by email address as a comment ```bash ssh-keygen -f "$HOME/.ssh/github_id_ed25519" -t ed25519 -C "your_email@example.com" ``` --- ### Note You can use any email address to generate the SSH key pair. It only serves as a label and doesn’t have to be the same address you use to log into GitHub. --- The SSH keygen command asks us to specify a “**passphrase**” for the private key. Unlike a password, a passphrase can contain spaces. The passphrase should be several words long and is then just as easy to remember as it is difficult to guess. Include some digits or special characters for increased security. Type the passphrase and press “Enter”. Repeat the process to complete the creation of the SSH key pair. [![Image: Creating an SSH key pair for GitHub](https://www.ionos.com/digitalguide/fileadmin/_processed_/8/6/csm_creating-an-ssh-key-pair-for-github_473bb47bce.webp "Creating an SSH key pair for GitHub")](https://www.ionos.com/digitalguide/fileadmin/DigitalGuide/Screenshots_2022/creating-an-ssh-key-pair-for-github.png) We have created the SSH key for use with GitHub. --- ### Tip We use the Ed25519 algorithm for our key pair. In fact, there’s a whole range of algorithms available. We present the [encryption methods at a glance](https://www.ionos.com/digitalguide/server/security/encryption-software/ "Encryption software") in a separate article. --- Before we can use our freshly generated SSH key with GitHub, we perform one more step. This is optional, but highly recommended. We **add the private key to the “SSH agent”**. This is a background program that runs on the local system. Run the following command from the command line and enter the passphrase when asked: - Windows / Linux ```none ssh-add ~/.ssh/github_id_ed25519 ``` - macOS to 11 Big Sur ```none ssh-add -K ~/.ssh/github_id_ed25519 ``` - macOS from 12 Monterey ```none ssh-add --apple-use-keychain ~/.ssh/github_id_ed25519 ``` The SSH agent has access to added private keys and allows you to **use them to connect without entering the passphrase every time.** But the SSH agent can do even more: --- ### Quote > “SSH agent is a program that can keep a user’s private key, so that the private key passphrase only needs to be supplied once. A connection to the agent can also be forwarded when logging into a server, allowing SSH commands on the server to use the agent running on the user’s desktop.” / Source: https://www.ssh.com/academy/ssh/keygen#adding-the-key-to-ssh-agent --- ### Deposit SSH key with GitHub We have created an SSH key pair on our local system. This provides one half of the encrypted communication when using GitHub with SSH. The remaining step is to **deposit the public SSH key with GitHub**. [![Image: The GitHub account settings page](https://www.ionos.com/digitalguide/fileadmin/_processed_/2/4/csm_the-github-account-settings-page_d267f89b90.webp "The GitHub account settings page")](https://www.ionos.com/digitalguide/fileadmin/DigitalGuide/Screenshots_2022/the-github-account-settings-page.png) Log in to your GitHub account and navigate to the key settings page. [![Image: GitHub settings to add an SSH key](https://www.ionos.com/digitalguide/fileadmin/_processed_/6/b/csm_github-settings-to-add-an-ssh-key_67a1793af1.webp "GitHub settings to add an SSH key")](https://www.ionos.com/digitalguide/fileadmin/DigitalGuide/Screenshots_2022/github-settings-to-add-an-ssh-key.png) Click “New SSH key” under “SSH keys” to open the page to add a new key. Now we need the **contents of the public key**. Switch to your local command line and enter the following command: ```none cat ~/.ssh/github_id_ed25519.pub ``` --- ### Note Caution: the filename ends in .pub for the “public key”. However, the private key doesn’t end in .priv or the like. Instead, the private key has no ending. Only share the public key with GitHub and other third parties. --- [![Image: content of the public key in the command line](https://www.ionos.com/digitalguide/fileadmin/_processed_/a/e/csm_content-of-the-public-key-in-the-command-line_22bd1fbbd2.webp "content of the public key in the command line")](https://www.ionos.com/digitalguide/fileadmin/DigitalGuide/Screenshots_2022/content-of-the-public-key-in-the-command-line.png) Copy the issued public key and switch back to the GitHub page. [![Image: SSH public key copied to GitHub settings page](https://www.ionos.com/digitalguide/fileadmin/_processed_/0/e/csm_ssh-public-key-copied-to-github-settings-page_390c47024a.webp "SSH public key copied to GitHub settings page")](https://www.ionos.com/digitalguide/fileadmin/DigitalGuide/Screenshots_2022/ssh-public-key-copied-to-github-settings-page.png) Paste the copied public key and optionally assign a title. Save the changes by clicking “Add SSH key”. [![Image: Overview of added SSH keys in GitHub](https://www.ionos.com/digitalguide/fileadmin/_processed_/c/8/csm_overview-of-added-ssh-keys-in-github_1a878a871c.webp "Overview of added SSH keys in GitHub")](https://www.ionos.com/digitalguide/fileadmin/DigitalGuide/Screenshots_2022/overview-of-added-ssh-keys-in-github.png) The newly added SSH key for GitHub will be shown in the key overview. ### Access GitHub repository with an SSH key We have generated the keys locally and deposited the public SSH key with GitHub. First, let’s test if the connection works using the following command: ```none ssh -T git@github.com ``` [![Image: Positive connection test to GitHub via SSH](https://www.ionos.com/digitalguide/fileadmin/_processed_/f/9/csm_positive-connection-test-to-github-via-ssh_d049f6823b.webp "Positive connection test to GitHub via SSH")](https://www.ionos.com/digitalguide/fileadmin/DigitalGuide/Screenshots_2022/positive-connection-test-to-github-via-ssh.png) The encrypted connection with GitHub works. If this is your **first time connecting to GitHub from this machine**, you’ll also be prompted to add the server to the “known hosts”: [![Image: Adding the GitHub server to the SSH known hosts](https://www.ionos.com/digitalguide/fileadmin/_processed_/e/1/csm_adding-the-github-server-to-the-ssh-known-hosts_8abe87d7d5.webp "Adding the GitHub server to the SSH known hosts")](https://www.ionos.com/digitalguide/fileadmin/DigitalGuide/Screenshots_2022/adding-the-github-server-to-the-ssh-known-hosts.png) Confirm the addition of the server by typing “yes” and pressing Enter. When accessing GitHub repositories, **we distinguish between read and write access**. Public repositories can be read by anyone. No authentication, i.e., no SSH key, is required. To **download a repository as a local copy**, use the Git clone command. We’ll demonstrate this using the repository of the popular network tool cURL as an example. We visit the GitHub page of the public [cURL repository](https://github.com/curl/curl "cURL repository of GitHub") and copy the clone URL: [![Image: Overview page of the cURL repository](https://www.ionos.com/digitalguide/fileadmin/_processed_/1/4/csm_overview-page-of-the-curl-repository_d52c47df2e.webp "Overview page of the cURL repository")](https://www.ionos.com/digitalguide/fileadmin/DigitalGuide/Screenshots_2022/overview-page-of-the-curl-repository.png) Overview of the cURL repository code / Source: https://github.com/curl/curl [![Image: Clone URL of the cURL repository copied](https://www.ionos.com/digitalguide/fileadmin/_processed_/5/2/csm_clone-url-of-the-curl-repository-copied_a77de188dc.webp "Clone URL of the cURL repository copied")](https://www.ionos.com/digitalguide/fileadmin/DigitalGuide/Screenshots_2022/clone-url-of-the-curl-repository-copied.png) We copy the “clone URL” of the cURL repository / Source: https://github.com/curl/curl Equipped with the clone URL, we switch back to the local command line. We create a sample folder repo on the desktop and switch to that. We then **clone the cURL repository** by calling up Git clone with the clone URL: ```none cd ~/Desktop/ mkdir -p repo && cd repo git clone https://github.com/curl/curl.git ``` [![Image: Cloning the cURL repository in the local command line](https://www.ionos.com/digitalguide/fileadmin/_processed_/a/6/csm_cloning-the-curl-repository-in-the-local-command-line_53d35286a4.webp "Cloning the cURL repository in the local command line")](https://www.ionos.com/digitalguide/fileadmin/DigitalGuide/Screenshots_2022/cloning-the-curl-repository-in-the-local-command-line.png) The cloned cURL repository is now located in the curl folder. We **switch to the cURL repository folder** and use the Git status command to display the status of the repository: ```none cd ~/Desktop/repo/curl/ git status ``` [![Image: Status of the local cURL repository](https://www.ionos.com/digitalguide/fileadmin/_processed_/3/5/csm_status-of-the-local-curl-repository_9912fc7851.webp "Status of the local cURL repository")](https://www.ionos.com/digitalguide/fileadmin/DigitalGuide/Screenshots_2022/status-of-the-local-curl-repository.png) Calling up the Git status shows that the status is normal. The Git pull command, which brings a repository up to date, also requires read-only access. We **run Git pull in the repository folder**. In principle, this works even if there are likely no changes yet: ```none git pull ``` Now, we try to write to the GitHub repository using the Git push command: ```none git push ``` [![Image: Result of Git pull and Git push of the local cURL repository](https://www.ionos.com/digitalguide/fileadmin/_processed_/3/d/csm_result-of-git-pull-and-git-push-of-the-local-curl-repository_36b11a0789.webp "Result of Git pull and Git push of the local cURL repository")](https://www.ionos.com/digitalguide/fileadmin/DigitalGuide/Screenshots_2022/result-of-git-pull-and-git-push-of-the-local-curl-repository.png) Git pull works. Git push fails because our machine is not authenticated. What’s going on here? **The clone URL** used to clone the public cURL repository **starts with HTTPS**. Accordingly, for our local clone, an HTTPS URL is stored as “Origin”. We check the origin with the Git show command: ```none git remote -v show ``` [![Image: Remotes of the local cURL repository in the command line](https://www.ionos.com/digitalguide/fileadmin/_processed_/5/6/csm_remotes-of-the-local-curl-repository-in-the-command-line_f1d648edf0.webp "Remotes of the local cURL repository in the command line")](https://www.ionos.com/digitalguide/fileadmin/DigitalGuide/Screenshots_2022/remotes-of-the-local-curl-repository-in-the-command-line.png) The URLs for the Git operations fetch and push are displayed. For read access, an HTTPS URL is sufficient, but **an SSH key is required to write to GitHub repositories**. This is because user authentication via username / password [is no longer supported on GitHub as of August 2021](https://github.blog/changelog/2021-08-12-git-password-authentication-is-shutting-down/ "Changelog of Github"). We use a trick to test Git push anyway. First, we [create on GitHub](https://github.com/new "Mask for creating a repository") our own empty repository: [![Image: Create a new repository on GitHub](https://www.ionos.com/digitalguide/fileadmin/_processed_/b/c/csm_create-a-new-repository-on-github_b4a60b8a88.webp "Create a new repository on GitHub")](https://www.ionos.com/digitalguide/fileadmin/DigitalGuide/Screenshots_2022/create-a-new-repository-on-github.png) We create a new repository with the name “test”. [![Image: Overview of an empty GitHub repository](https://www.ionos.com/digitalguide/fileadmin/_processed_/9/6/csm_overview-of-an-empty-github-repository_23adf91702.webp "Overview of an empty GitHub repository")](https://www.ionos.com/digitalguide/fileadmin/DigitalGuide/Screenshots_2022/overview-of-an-empty-github-repository.png) Our empty GitHub repository contains instructions to fill it with code. Following the instructions on GitHub, **we change the push URL of the local cURL clone** on our system to use our empty GitHub repository as origin. Furthermore, we set the branch to “main”. We then execute the Git push. The operation completes successfully and uses our previously created SSH key to authenticate us to GitHub. ```none git remote set-url origin git@github.com:/test.git git branch -M main git push -u origin main ``` [![Image: Changing the push URL and Git push from the local repository](https://www.ionos.com/digitalguide/fileadmin/_processed_/d/7/csm_changing-the-push-url-and-git-push-from-the-local-repository_daa8bb5e1e.webp "Changing the push URL and Git push from the local repository")](https://www.ionos.com/digitalguide/fileadmin/DigitalGuide/Screenshots_2022/changing-the-push-url-and-git-push-from-the-local-repository.png) Git push works after changing the push URL. ### Use multiple SSH keys for different GitHub accounts It’s possible to use only **one SSH key for different GitHub or other accounts** without any problems. Remember: we can share the public key without hesitation. Technically, it’s quite possible to **use your own SSH keys for different services and sites**. There are two possible methods: 1. Call up SSH command with parameters 2. Create SSH config file SSH commands with parameters may turn out to be very long, which is why we’re not showing this approach here. In general, it’s **more convenient to work with an SSH config file**. This requires a little more effort to configure your own system, but it only needs to be done once. Here’s an overview of the folders and files involved in SSH configuration:
SSH configuration Path Explanation
Config folder ~/.ssh/ Contains SSH configuration and key pairs.
Private key ~/.ssh/key-name Private key from a key pair.
Public key ~/.ssh/key-name.pub Public key from a key pair.
Config file ~/.ssh/config SSH configuration file.
Known hosts ~/.ssh/known\_hosts List of hosts connected in the past.
**First, we create the SSH config file**. We create the file, adjust the user rights and open it in the command line editor: ```none touch ~/.ssh/config chmod 600 ~/.ssh/config nano ~/.ssh/config ``` Then, **copy the following block into the editor** and follow the screenshots to save the file: ```none # Github Host github github.com HostName github.com User git IdentityFile "~/.ssh/github_id_ed25519" IdentitiesOnly yes ``` [![Image: Inserting the GitHub configuration into SSH config file](https://www.ionos.com/digitalguide/fileadmin/_processed_/3/c/csm_inserting-the-github-configuration-into-ssh-config-file_f479f56e80.webp "Inserting the GitHub configuration into SSH config file")](https://www.ionos.com/digitalguide/fileadmin/DigitalGuide/Screenshots_2022/inserting-the-github-configuration-into-ssh-config-file.png) Paste the configuration block and press Ctrl + X to write the changes and close the editor. [![Image: Writing the modified SSH config file](https://www.ionos.com/digitalguide/fileadmin/_processed_/6/9/csm_writing-the-modified-ssh-config-file_825439011e.webp "Writing the modified SSH config file")](https://www.ionos.com/digitalguide/fileadmin/DigitalGuide/Screenshots_2022/writing-the-modified-ssh-config-file.png) Confirm the name of the file by pressing Enter. [![Image: Confirming the changes to the SSH config file](https://www.ionos.com/digitalguide/fileadmin/_processed_/5/5/csm_confirming-the-changes-to-the-ssh-config_file_abd237ba18.webp "Confirming the changes to the SSH config file")](https://www.ionos.com/digitalguide/fileadmin/DigitalGuide/Screenshots_2022/confirming-the-changes-to-the-ssh-config_file.png) Confirm writing the changes by pressing Enter. After inserting the GitHub configuration block, an SSH connection can be established by specifying the specified host abbreviation github: ```none ssh -T github ``` Follow the schema shown to **add configuration blocks for additional services or accounts to the SSH config file**. Here’s an overview of the parameters that are used:
Setting Explanation Example
Host Can contain any number of names. github.com github
HostName Host name of the remote system running SSH. An IP address can also be used. github.com
User Git user on the remote system. Must be applied exactly. git
IdentityFile Absolute path to the private key. Adjust this if you use multiple keys. ~/.ssh/github\_id\_ed25519
IdentitiesOnly Specifies that access for this host must be by key only. yes
One final tip. If you **create SSH configurations for multiple hosts with their own keys**, you should add a block of settings for unlisted hosts at the end of the file: ```none # For all hosts Host * IdentitiesOnly no IgnoreUnknown UseKeychain, AddKeysToAgent UseKeychain yes AddKeysToAgent yes ``` This allows **access without an SSH key to unspecified hosts**. You can connect to a host via SSH command with your username and enter the password when connecting: ```none ssh user@host ``` Without the line “IdentitiesOnly no” in the final configuration, SSH tries all keys in ~./ssh/ one after the other to connect to the server. If there’s no matching key, the error “Too many authentication failures” occurs. This is a markdown version of: [https://www.ionos.com/digitalguide/websites/web-development/ssh-key-with-github/](https://www.ionos.com/digitalguide/websites/web-development/ssh-key-with-github/) for AI/LLM consumption.