Connect GitHub SSH

Requirements and preparation

Before generating your keys, ensure the required software is installed for your operating system.

Windows 11

Windows 11 includes an open-source SSH client natively, but you will need Git to use it with GitHub.

  • What to install: Git for Windows.
  • Download the installer from the official website: https://git-scm.com/downloads.
  • During installation, select Git Bash as your default terminal experience, as it provides a clean Linux-like environment for handling SSH keys.

macOS

macOS comes pre-installed with standard SSH tools natively in the Terminal application. You only need to ensure the Git CLI tools are active.

  • What to install: Xcode Command Line Tools.
  • Open the Terminal application and run:
xcode-select --install

Debian Linux

Debian minimal installations may lack the necessary network and version control packages.

  • What to install: git and openssh-client.
  • Open your terminal and update your package repository manager:
sudo apt update && sudo apt install git openssh-client -y

Generating the SSH key

Modern security standards heavily favor the Ed25519 algorithm over older RSA keys because it is cryptographically stronger, faster, and generates shorter keys.

Open your platform's terminal (Git Bash for Windows, Terminal for macOS/Debian) and follow these platform-specific variations to build your cryptographic identity.

Windows 11

  1. Run the generator using Ed25519, substituting your GitHub email address:
ssh-keygen -t ed25519 -C "your_email@example.com"

  1. Press Enter to accept the default file path: /c/Users/YourUsername/.ssh/id_ed25519.

  2. Enter a secure passphrase when prompted (highly recommended for local security).

  3. Start the background SSH agent:

eval "$(ssh-agent -s)"
  1. Add the private key to the agent:
ssh-add ~/.ssh/id_ed25519
  1. Copy the public key to your clipboard:
clip < ~/.ssh/id_ed25519.pub

macOS

  1. Generate the key:
ssh-keygen -t ed25519 -C "your_email@example.com"

  1. Press Enter to accept the default file location: ~/.ssh/id_ed25519.

  2. Configure your SSH config file: macOS requires an extra step to store your passphrase securely inside your system Keychain.

  3. Create or edit your local config file:

nano ~/.ssh/config
  1. Paste the following configuration into the file:
Host github.com
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519

  1. Press Ctrl + O then Enter to save, and Ctrl + X to exit nano.

  2. Start the agent and add your key:

eval "$(ssh-agent -s)"
ssh-add --apple-use-keychain ~/.ssh/id_ed25519
  1. Copy the public key to your clipboard:
pbcopy < ~/.ssh/id_ed25519.pub

Debian Linux

  1. Generate the key:
ssh-keygen -t ed25519 -C "your_email@example.com"

  1. Press Enter to accept the default path: ~/.ssh/id_ed25519.

  2. Start the background agent:

eval "$(ssh-agent -s)"
  1. Add the private key to the agent:
ssh-add ~/.ssh/id_ed25519
  1. Copy the public key to your clipboard. Since Linux distributions lack a universal built-in clipboard utility, print the contents to the terminal screen, highlight it manually, and copy it (Ctrl + Shift + C):
cat ~/.ssh/id_ed25519.pub

Adding the key to GitHub

  1. Log in to your account on github.com.
  2. Click your profile picture in the top-right corner and select Settings.
  3. In the left-hand sidebar, click SSH and GPG keys.
  4. Click the green New SSH Key button.
  5. Provide a recognizable name in the Title field.
  6. Set the Key type field to Authentication Key.
  7. Paste your public key directly into the Key textarea.
  8. Click Add SSH Key.
  9. Confirm your GitHub password if prompted.

Testing the connection

  1. To confirm your local computer establishes a successful secure link with the remote server, open your terminal window on any environment and run the test script:
ssh -T git@github.com
  1. When running this connection check for the first time, your system will display a fingerprint warning:
The authenticity of host 'github.com (IP_ADDRESS)' can't be established.
ED25519 key fingerprint is SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0tcXYZmqw/XY0BuDU.
Are you sure you want to continue connecting (yes/no/[fingerprint])?
  1. Type yes and press Enter. The terminal will update with a confirmation message:
Hi username! You've successfully authenticated, but GitHub does not provide shell access.

If you see your correct GitHub account name in that final response string, your secure authentication deployment is fully complete and operational.

Adding a signing key

  1. Go to your GitHub Settings and select SSH and GPG keys.
  2. Click New SSH Key.
  3. Provide a recognizable name in the Title field.
  4. Change the Key type dropdown to Signing Key.
  5. Paste your public key id_ed25519.pub just like you did before and save.

Signing local commits

  1. Open your terminal (Git Bash on Windows, or Terminal on macOS/Linux).
  2. Tell Git to use SSH for signing (instead of GPG):
git config --global gpg.format ssh
  1. Point Git to your public key file:
git config --global user.signingkey ~/.ssh/id_ed25519.pub
  1. Tell Git to sign all future commits automatically:
git config --global commit.gpgsign true
  1. Windows only: point Git at the native OpenSSH signer. This step is easy to miss because signing looks configured without it, yet commits still work in some terminals — see the warning below for why.
git config --global gpg.ssh.program "C:/Windows/System32/OpenSSH/ssh-keygen.exe"
  1. Make a new commit, push it to GitHub, and you will see the green Verified badge appear.

Windows: why git commit may hang forever. Signing (step 4) is separate from the transport client you set with core.sshCommand — signing uses gpg.ssh.program, which defaults to a bare ssh-keygen resolved from your PATH. Git for Windows bundles its own MSYS ssh-keygen (in C:\Program Files\Git\usr\bin), and that build cannot talk to the native Windows ssh-agent (it looks for a Unix-socket agent, while the Windows agent listens on a named pipe). So when a commit runs from Git Bash, git calls the MSYS ssh-keygen, which can't find your unlocked key in the agent, falls back to your passphrase-protected key file, and blocks on an Enter passphrase for ... prompt — the commit appears to hang. PowerShell, cmd, and GitHub Desktop happen to resolve ssh-keygen to the Windows one (C:\Windows\System32\OpenSSH), which reaches the agent, which is why it "works there but not in Git Bash." Step 5 removes the ambiguity by naming the Windows ssh-keygen explicitly, so signing works the same in every terminal.

Configuring SSH for GUI Applications

When using GUI applications like GitHub Desktop, commits and pushes may fail if your SSH key has a passphrase. This happens because the graphical application lacks a terminal interface to prompt you for the password. To fix this, you must store your unlocked key in your system's background SSH agent.

Windows 11

  1. Open your Start menu, type PowerShell, right-click it, and select Run as Administrator.
  2. Run this command to set the native Windows SSH Agent to start automatically:
Get-Service -Name ssh-agent | Set-Service -StartupType Automatic
  1. Start the service immediately:
Start-Service ssh-agent
  1. Close the Administrator PowerShell window and open a standard, non-administrator PowerShell window.
  2. Add your key to the agent. Make sure to replace YourUsername with your actual Windows account name. You will be prompted to enter your passphrase once:
ssh-add C:\Users\YourUsername\.ssh\id_ed25519
  1. Tell Git to prioritize the Windows native SSH client to ensure background compatibility with GitHub Desktop:
git config --global core.sshCommand "C:/Windows/System32/OpenSSH/ssh.exe"
  1. Completely restart GitHub Desktop.

macOS

If you followed the initial setup and configured your ~/.ssh/config file, macOS should automatically handle passphrases using the system Keychain. If your GUI application is still failing, ensure the key is actively loaded into the Keychain.

  1. Open the Terminal application.
  2. Manually add the key to your Apple Keychain. You will be prompted for your passphrase:
ssh-add --apple-use-keychain ~/.ssh/id_ed25519
  1. Completely restart your Git GUI application.

Debian Linux

On Debian, GUI applications launched from desktop shortcuts may not inherit the SSH agent environment variables started in a standard terminal session.

  1. Open your terminal.
  2. Ensure the key is added to your active agent session. You will be prompted for your passphrase:
ssh-add ~/.ssh/id_ed25519
  1. For a more permanent solution across desktop sessions, install a keychain manager to persist your unlocked key globally:
sudo apt install keychain
  1. Add the keychain initializer to your bash profile:
echo 'eval $(keychain --eval --agents ssh id_ed25519)' >> ~/.bashrc
  1. Restart your terminal. You will only need to enter your passphrase once upon login, and your GUI applications will function seamlessly.