A Step-by-Step Guide to Setting Up Custom SSH Keys for GitHub

Securely connecting to GitHub using SSH keys enhances your workflow by eliminating the need for passwords during authentication. This guide will walk you through generating a key pair, configuring it on GitHub, and troubleshooting common issues. Step 1: Generate an SSH Key Pair Objective: Create a secure SSH key pair (public and private) to authenticate with GitHub. Process: Open your terminal. Run the following command to generate an Ed25519 SSH key pair: Generate SSH key with your_custom_file_name! ssh-keygen -t ed25519 -f ~/.ssh/file_name -C "your_github@email.address" -f your custom file_name with path -C comment ( required | optional)? -f output_keyfile The -f option specifies the filename for the private key. Choose a meaningful name, like localpc or hostingdomaincom Step 2: Add Your Public Key to GitHub Objective: Authorize your public key for SSH authentication on your GitHub account. Process: Copy the public key: Run this command to copy your public key to the clipboard: cat ~/.ssh/file_name.pub Access GitHub Settings: Go to GitHub Account Settings . Click on "Add SSH Key" and provide a title (e.g., "Custom SSH Key"). Paste the public key: Paste the content of custom_key.pub into the text box. Click "Add key" to save. Step 3: Configure SSH to Use Your Custom Key Objective: Tell SSH to use your custom key for connections to GitHub. Test your connection ssh -i ~/.ssh/file_name -T git@github.com 2.Edit the SSH configuration file: Open the following file in a text editor: nano ~/.ssh/config Host github.com HostName github.com User git IdentityFile ~/.ssh/file_name IdentitiesOnly yes Save and exit: Press Ctrl+O to write changes. Press Ctrl+X to close the editor. Common Issues & Solutions Issue 1: "Permission denied (publickey)" when testing SSH connection Ensure your public key is correctly added to GitHub. Verify the private key filename in ~/.ssh/config matches the public key. Testing connection ssh -T git@github.com git@github.com: Permission denied (publickey). Testing connection with verbose mode (debug) ssh -vT git@github.com ... debug1: SSH2_MSG_SERVICE_ACCEPT received debug1: Authentications that can continue: publickey debug1: Next authentication method: publickey debug1: Trying private key: /home/user/.ssh/id_rsa debug1: Trying private key: /home/user/.ssh/id_ecdsa debug1: Trying private key: /home/user/.ssh/id_ecdsa_sk debug1: Trying private key: /home/user/.ssh/id_ed25519 debug1: Trying private key: /home/user/.ssh/id_ed25519_sk debug1: Trying private key: /home/user/.ssh/id_xmss debug1: Trying private key: /home/user/.ssh/id_dsa debug1: No more authentication methods to try. git@github.com: Permission denied (publickey). Github doesn't know your custom file name follow Step 3. Check your current remote URL List current remotes: git remote -v Replace the HTTPS URL with the SSH equivalent in your repository. For example: bash git remote set-url origin git@github.com:username/repo.git Issues: Local "master" Branch Renaming to "main" Description: Commands Used: git push -u origin main Error received: "src refspec main does not match any" git branch -M master main Expected Outcome: Successfully rename the local master branch to main and set it as the default branch for future pushes. Objectives: Local git repository with master branch Github repository with main branch git push -u origin main error: src refspec main does not match any Rename local "master" branch to "main" git branch -M main git branch help: git branch (-m | -M) [] _ Issue: SSH Agent not open _ ssh-add ~/.ssh/your_custom_file_name error: Could not open a connection to your authentication agent. Solution: eval "$(ssh-agent -s)" ssh-add ~/.ssh/file_name Identity added: /home/user/.ssh/file_name To automatically start the SSH agent on login, edit your shell configuration file (e.g., ~/.bashrc) and add: nvim ~/.bashrc file # START Start SSH agent automatically if [ -z "$SSH_AUTH_SOCK" ]; then # Check if ssh-agent is already running ps -aux | grep ssh-agent | grep -v grep >/dev/null if [ $? -ne 0 ]; then # Start ssh-agent eval "$(ssh-agent -s)" fi fi # END Start SSH agent automatically

May 4, 2025 - 15:31

A Step-by-Step Guide to Setting Up Custom SSH Keys for GitHub

Securely connecting to GitHub using SSH keys enhances your workflow by eliminating the need for passwords during authentication. This guide will walk you through generating a key pair, configuring it on GitHub, and troubleshooting common issues.

Step 1: Generate an SSH Key Pair

Objective:
Create a secure SSH key pair (public and private) to authenticate with GitHub.

Process:

Open your terminal.
Run the following command to generate an Ed25519 SSH key pair:

Generate SSH key with your_custom_file_name!
ssh-keygen -t ed25519 -f ~/.ssh/file_name -C "your_github@email.address"

-f your custom file_name with path
-C comment ( required | optional)?
-f output_keyfile
The -f option specifies the filename for the private key. Choose a meaningful name, like localpc or hostingdomaincom

Step 2: Add Your Public Key to GitHub

Objective:
Authorize your public key for SSH authentication on your GitHub account.

Process:

Copy the public key: Run this command to copy your public key to the clipboard: cat ~/.ssh/file_name.pub
Access GitHub Settings: Go to GitHub Account Settings . Click on "Add SSH Key" and provide a title (e.g., "Custom SSH Key").
Paste the public key: Paste the content of custom_key.pub into the text box. Click "Add key" to save.

Step 3: Configure SSH to Use Your Custom Key

Objective:

Tell SSH to use your custom key for connections to GitHub.

Test your connection ssh -i ~/.ssh/file_name -T git@github.com

2.Edit the SSH configuration file:

Open the following file in a text editor:
nano ~/.ssh/config

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

Save and exit: Press Ctrl+O to write changes. Press Ctrl+X to close the editor.

Common Issues & Solutions

Issue 1: "Permission denied (publickey)" when testing SSH connection

Ensure your public key is correctly added to GitHub.
Verify the private key filename in ~/.ssh/config matches the public key. Testing connection ssh -T git@github.com git@github.com: Permission denied (publickey).

Testing connection with verbose mode (debug)
ssh -vT git@github.com

...
debug1: SSH2_MSG_SERVICE_ACCEPT received
debug1: Authentications that can continue: publickey
debug1: Next authentication method: publickey
debug1: Trying private key: /home/user/.ssh/id_rsa
debug1: Trying private key: /home/user/.ssh/id_ecdsa
debug1: Trying private key: /home/user/.ssh/id_ecdsa_sk
debug1: Trying private key: /home/user/.ssh/id_ed25519
debug1: Trying private key: /home/user/.ssh/id_ed25519_sk
debug1: Trying private key: /home/user/.ssh/id_xmss
debug1: Trying private key: /home/user/.ssh/id_dsa
debug1: No more authentication methods to try.
git@github.com: Permission denied (publickey).

Github doesn't know your custom file name follow Step 3.

Check your current remote URL

List current remotes:
git remote -v

Replace the HTTPS URL with the SSH equivalent in your repository. For example:
bash
git remote set-url origin git@github.com:username/repo.git

Issues: Local "master" Branch Renaming to "main"

Description:

Commands Used:
git push -u origin main
Error received: "src refspec main does not match any"
git branch -M master main
Expected Outcome:
Successfully rename the local master branch to main and set it as the default branch for future pushes.

Objectives:

Local git repository with master branch
Github repository with main branch

git push -u origin main
error: src refspec main does not match any
Rename local "master" branch to "main"
git branch -M main
git branch help: git branch (-m | -M) []
_

Issue: SSH Agent not open

ssh-add ~/.ssh/your_custom_file_name
error: Could not open a connection to your authentication agent.

Solution:
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/file_name
Identity added: /home/user/.ssh/file_name

To automatically start the SSH agent on login, edit your shell configuration file (e.g., ~/.bashrc) and add:
nvim ~/.bashrc file

# START Start SSH agent automatically
if [ -z "$SSH_AUTH_SOCK" ]; then
  # Check if ssh-agent is already running
  ps -aux | grep ssh-agent | grep -v grep >/dev/null
  if [ $? -ne 0 ]; then
    # Start ssh-agent
    eval "$(ssh-agent -s)"
  fi
fi
# END Start SSH agent automatically