How to configure command line git to use ssh key

Configure Git for SSH Key Authentication

Learn how to set up command-line Git to use SSH keys for secure and password-less authentication with remote repositories like GitHub.

Using SSH keys for Git authentication provides a more secure and convenient way to interact with remote repositories compared to HTTPS with username/password. Once configured, you won't need to enter your credentials every time you push or pull code. This guide will walk you through the process of generating an SSH key pair, adding it to your SSH agent, and configuring Git to use it, specifically focusing on GitHub as a common use case.

Understanding SSH Keys

An SSH key pair consists of two parts: a public key and a private key. The public key can be shared freely and is added to your remote Git hosting service (e.g., GitHub, GitLab, Bitbucket). The private key must be kept secret and secure on your local machine. When you connect to a remote repository, your local SSH client uses your private key to prove your identity to the server, which then verifies it against the public key you provided. This handshake ensures secure communication.

sequenceDiagram
    participant User as Your Local Machine
    participant GitHost as Remote Git Host (e.g., GitHub)

    User->>User: Generate SSH Key Pair (Public + Private)
    User->>GitHost: Upload Public Key
    Note over GitHost: Public Key stored for user
    User->>GitHost: Git Command (e.g., `git push`)
    GitHost->>User: Request Authentication
    User->>User: SSH Agent uses Private Key
    User->>GitHost: Send Signed Challenge
    GitHost->>GitHost: Verify Signature with Stored Public Key
    alt Authentication Successful
        GitHost->>User: Grant Access
    else Authentication Failed
        GitHost->>User: Deny Access
    end

SSH Key Authentication Flow for Git

Generating a New SSH Key Pair

If you don't already have an SSH key pair, you'll need to generate one. It's recommended to use a strong encryption algorithm like ED25519. You can also add a passphrase to your private key for an extra layer of security; this passphrase will be requested when you first use the key in a session.

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

Generate a new ED25519 SSH key pair

When prompted, you can press Enter to accept the default file location (~/.ssh/id_ed25519) and then enter a strong passphrase (or leave it empty for no passphrase, though this is less secure).

Adding Your SSH Key to the SSH Agent

The SSH agent is a program that runs in the background and holds your private keys in memory, so you don't have to enter your passphrase every time you use the key. You'll need to start the agent and then add your key to it.

1. Start the SSH agent

First, ensure the SSH agent is running. This command starts the agent if it's not already running and sets the necessary environment variables.

2. Add your SSH private key to the agent

Now, add your private key to the SSH agent. If you used a different filename or path, adjust ~/.ssh/id_ed25519 accordingly.

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

Start SSH agent and add your private key

Adding Your Public Key to GitHub

For GitHub (or any other Git hosting service), you need to add your public key to your account settings. This allows the service to recognize your machine when you attempt to connect.

1. Copy your public key

Display your public key and copy its entire content to your clipboard. The public key typically ends with .pub.

2. Navigate to GitHub SSH settings

Go to GitHub, click on your profile picture, then 'Settings' -> 'SSH and GPG keys'.

3. Add new SSH key

Click 'New SSH key' or 'Add SSH key'. Give it a descriptive title (e.g., 'My Work Laptop') and paste your copied public key into the 'Key' field. Click 'Add SSH key'.

cat ~/.ssh/id_ed25519.pub

Display your public key to copy

Testing Your SSH Connection

After adding your public key to GitHub, it's a good practice to test the connection to ensure everything is set up correctly.

ssh -T git@github.com

Test your SSH connection to GitHub

You should see a message like Hi username! You've successfully authenticated, but GitHub does not provide shell access. This confirms your SSH key is working correctly.

Configuring Git to Use SSH

Finally, ensure your Git repositories are configured to use the SSH protocol. If you cloned a repository using HTTPS, you'll need to update its remote URL. For new repositories, always use the SSH clone URL.

1. Check current remote URL

Navigate into your local Git repository and check its current remote URL. If it starts with https://, you'll need to change it.

2. Update remote URL to SSH

Change the remote URL to use the SSH protocol. Replace username/repo.git with your actual repository path.

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

Update Git remote URL to use SSH

Now, when you perform Git operations like git pull or git push, Git will automatically use your SSH key for authentication, providing a seamless and secure experience.