DEV Community

Cover image for How to configure SSH for accessing remote repositories
capscode
capscode

Posted on • Originally published at capscode.in

How to configure SSH for accessing remote repositories

#productivity #devops #learning #security

Introduction: SSH vs HTTPS for GitHub Authentication

When working with remote repositories, there are two primary ways developers authenticate their local machines with remote repositories:

  1. HTTPS Authentication
  2. SSH (Secure Shell) Authentication

NOTE: In this article we will see the steps for GitHub, but for other service providers the steps will be similar.

1. HTTPS Login

With HTTPS, every time you interact with a remote repository (like git push, git pull, or git clone), GitHub asks for your username and personal access token (PAT)/Password.

  • Requires credential caching or a credential manager to avoid typing every time
  • Simple to set up
  • Can be cumbersome if working with multiple accounts.

Learn how to setup multiple git/github account for SSH

2. SSH Authentication

SSH uses a public-private key pair for secure, password-less authentication between your machine and GitHub.
Once you add your public SSH key to your GitHub account, your computer can securely authenticate with GitHub without needing to enter your username and password or PAT.

  • No need to enter credentials for every operation
  • More secure, encrypted connection
  • Easily manage multiple accounts using SSH config Link
  • Perfect for frequent collaborators or CI/CD setups

Why Choose SSH?

  • Secure, encrypted connection
  • No repeated password/token prompts
  • Clean handling of multiple GitHub accounts
  • Works well for automation, CI/CD, and team setups

Let's see the steps to configure the SSH Authentication.

Step 1: Check for Existing SSH Keys

See if you already have any SSH keys:

ls -al ~/.ssh
Enter fullscreen mode Exit fullscreen mode

If you see files like id_ed25519 and id_ed25519.pub, you might already have one & If you don't want to generate a new key then skip Step 2 & proceed to the next step.

If there is no file/key present or you want to generate a new keys then follow the next steps.

Step 2: Generate a New SSH Key

Use this command to create a new Ed25519 SSH key:

ssh-keygen -t ed25519 -C "your_email@example.com"
Enter fullscreen mode Exit fullscreen mode

NOTE: This will replace the existing key if any and it will affect the auth if configured any.

After running this command you will see 2 files named id_ed25519 (private key) and id_ed25519.pub (public key) in your .ssh folder.

If you need to keep the existing ones for a different use (another service or project), generate a new key with a custom file name:

ssh-keygen -t ed25519 -C "your_email@example.com" -f ~/.ssh/custom_key_name
Enter fullscreen mode Exit fullscreen mode

After running this command you will see 2 files named custom_key_name (private key) and custom_key_name.pub (public key) in your .ssh folder.

For time being, Let's assume we have id_ed25519 and id_ed25519.pub keys in our .ssh folder

Explanation:

  • -t ed25519: Specifies the key type (Ed25519 is modern, secure, and fast)
  • -C "your_email@example.com": A comment to label the key (usually your GitHub email)
  • -f ~/.ssh/custom_key_name: Defines the full path and filename of both public and private key being created

When prompted:

  • Enter file location: press Enter to accept default (/home/some_name/.ssh/id_ed25519)
  • Enter a passphrase (optional but recommended for extra security)

Step 3: Add the SSH Key to Your SSH Agent

Start the SSH agent:

eval "$(ssh-agent -s)"
Enter fullscreen mode Exit fullscreen mode

Add your new SSH private key to the agent:

ssh-add ~/.ssh/id_ed25519
Enter fullscreen mode Exit fullscreen mode

If you have generated custom key in step 2 then add that key as well,

ssh-add ~/.ssh/custom_key_name
Enter fullscreen mode Exit fullscreen mode

Check if its added:

ssh-add -l
Enter fullscreen mode Exit fullscreen mode

Optional: If you have multiple keys, manage them using an SSH config file (~/.ssh/config):

Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519
  IdentitiesOnly yes

Host bitbucket.org
  HostName bitbucket.org
  User git
  IdentityFile ~/.ssh/custom_key_name
  IdentitiesOnly yes
Enter fullscreen mode Exit fullscreen mode

NOTE: You don't need to add anything in the config file if there is only 1 key pairs.

Step 4: Add the SSH Public Key to GitHub

Copy the public key:

cat ~/.ssh/id_ed25519.pub
Enter fullscreen mode Exit fullscreen mode

Copy the output.

Go to:

  1. GitHub -> Settings
  2. SSH and GPG keys
  3. Click New SSH key
  4. Paste your public key
  5. Give it a Title and Save

Step 5: Test the SSH Connection

Verify your SSH connection to GitHub:

ssh -T git@github.com
Enter fullscreen mode Exit fullscreen mode

If you have multiple keys and have entry in the config file.

ssh -T git@github.com        # uses id_ed25519
ssh -T git@bitbucket.org     # uses custom_key_name
Enter fullscreen mode Exit fullscreen mode

NOTE: Here github.com and bitbucket.org is a host alias name (and not the keyname) you define in your ~/.ssh/config file.

On success, you should see:

Hi your_username! You've successfully authenticated...
Enter fullscreen mode Exit fullscreen mode

Step 6: Configure Git User Info (Optional but Recommended)

Set your Git global identity:

git config --global user.name "Your Name"
git config --global user.email "your_email@example.com"
Enter fullscreen mode Exit fullscreen mode

This identity is used for commit history metadata.

If you have multiple keys and have entry in the config file, then you have to setup git per repo identity

In GitHub repo

git config user.name "github user"
git config user.email "githubemail@exmaple.com"
Enter fullscreen mode Exit fullscreen mode

In BitBucket repo

git config user.name "bitbucket user"
git config user.email "bitbucketemail@bitbucket.com"
Enter fullscreen mode Exit fullscreen mode

Step 7: Set SSH Remote URL for Your Repository

If your repo is already cloned using HTTPS (example: https://github.com/username/repo.git), convert it to SSH:

  1. Check current remote: 
git remote -v
Enter fullscreen mode Exit fullscreen mode
  1. Change it to SSH: 
git remote set-url origin git@github.com:username/repository.git
Enter fullscreen mode Exit fullscreen mode

Replace username and repository with your actual GitHub username and repo name.

NOTE: Make sure that, If you have configured the config file then in place of github.com your host alias name will go.

From now on, when you git push or git pull, Git will use your SSH key for authentication.

Lets see some QnA

Q. What if we have only one key pair, in this case do we need any config file ?

A. No we don't need any config file.

Q. Will ssh -T git@github.com , ssh -T git@bitbucket.org uses same key if there is a single key pairs?

A. If You Have Only One Key (id_ed25519)

Let’s say your ~/.ssh/ folder has:

id_ed25519
id_ed25519.pub
Enter fullscreen mode Exit fullscreen mode

And you haven’t set any custom config.

Then:

Command What SSH Will Do
ssh -T git@github.com Offer the id_ed25519 key for authentication to GitHub
ssh -T git@bitbucket.org Offer the same id_ed25519 key for authentication to Bitbucket

Because — by default — SSH will:

  1. Check the SSH agent for loaded keys
  2. Then look for default keys in:
  • ~/.ssh/id_rsa
  • ~/.ssh/id_ecdsa
  • ~/.ssh/id_ed25519
  • etc.

If it finds only one key, it offers that key for any connection, whether it’s GitHub, Bitbucket, GitLab, or any other SSH service.

If both services (GitHub and Bitbucket) have this same public key registered in their settings, authentication will work fine.

Recap:

  • Generate SSH key
  • Add to SSH agent
  • Add public key to GitHub
  • Test SSH connection
  • Set or update remote URL
  • Optionally configure Git global username and email

Top comments (0)