Complete Git Authentication Troubleshooting Guide

Problem Description

While working with Git for code management, I encountered a classic authentication failure issue:

> git pull --tags origin main
ERROR: Repository not found.
fatal: Could not read from remote repository.

Please make sure you have the correct access rights and the repository exists.

This problem typically occurs in the following scenarios:

• Switched to a different GitHub account
• Previously used email is no longer accessible
• Local Git configuration doesn't match the current available account
• SSH key configuration issues

Environment Information

• Operating System: macOS
• Git Version: Standard version
• Problem Scenario: Can download GitHub repository content but unable to execute git pull operations
• Historical Context: Previously used a different account for commits, that email is no longer available

Complete Solution Workflow

Step 1: Problem Diagnosis

1.1 Check Current Git Configuration

git config --global user.name
git config --global user.email
git remote -v

1.2 Check Repository Status

git status

Issues Identified:

• Local repository remote URL points to incorrect user repository
• Authentication credentials don't match current available account

Step 2: Attempting SSH Authentication Fix

2.1 Test SSH Connection

ssh -T git@github.com

Result: SSH connection was successful, showing correct username authentication.

2.2 Update Remote Repository URL

git remote set-url origin git@github.com:YourUsername/repository-name.git

2.3 Test Pull Operation

git pull --tags origin main

Result: Still encountering "Connection closed by 140.82.112.4 port 22" error.

Step 3: Switch to HTTPS Authentication (Key Solution)

3.1 Change Remote Repository URL to HTTPS

git remote set-url origin https://github.com/YourUsername/repository-name.git

3.2 Verify URL Update

git remote -v

Should display:

origin  https://github.com/YourUsername/repository-name.git (fetch)
origin  https://github.com/YourUsername/repository-name.git (push)

3.3 Configure Pull Strategy

git config pull.rebase false  # Use merge strategy

3.4 Execute Pull Operation

git pull --tags origin main

Step 4: Resolve History Conflicts

After executing the pull, you may encounter "refusing to merge unrelated histories" error:

fatal: refusing to merge unrelated histories

4.1 Force Merge Unrelated Histories

git pull --tags origin main --allow-unrelated-histories

4.2 Resolve Potential Conflicts

If conflicts occur, follow these steps:

# Check conflict status
git status

# Manually edit conflict files, then after resolving conflicts
git add .
git commit -m "Merge remote and local histories"

Core Solution Points

1. SSH vs HTTPS Selection

• SSH Advantages: One-time setup, long-term use, no repeated password entry
• HTTPS Advantages: Better network compatibility, more stable in firewall environments
• Recommendation: If SSH connections are unstable, switch to HTTPS decisively

2. Authentication Credential Management

• When using HTTPS, you need GitHub Personal Access Token, not account password
• Token acquisition path: GitHub Settings → Developer settings → Personal access tokens

3. Repository History Merging

• When local and remote repository histories are unrelated, use --allow-unrelated-histories parameter
• This situation is common when merging independently created local and remote repositories

Prevention Measures

1. Regularly Update Git Configuration

# Ensure using current available email and username
git config --global user.name "CurrentUsername"
git config --global user.email "current-available-email@example.com"

2. Choose Appropriate Authentication Method

• Stable network environment: Prioritize SSH
• Restricted network environment: Recommend HTTPS
• Team collaboration: Standardize authentication methods to reduce issues

3. Backup Important Configurations

# Backup SSH keys
cp ~/.ssh/id_* ~/backup_ssh/

# Record important Git configurations
git config --list > git_config_backup.txt

Common Variant Problems

Problem 1: Permission denied (publickey)

Solution: Regenerate SSH keys and add to GitHub

Problem 2: Repository not found

Solution: Check repository URL and access permissions

Problem 3: Authentication failed

Solution: Update Personal Access Token

Troubleshooting Commands Summary

Essential Diagnostic Commands

# Check current configuration
git config --list
git remote -v
git status

# Test connections
ssh -T git@github.com
git ls-remote origin

# Clear authentication cache (macOS)
git config --global --unset credential.helper
security delete-internet-password -s github.com

Quick Fix Commands

# Switch to HTTPS (most reliable)
git remote set-url origin https://github.com/username/repo.git

# Configure pull strategy
git config pull.rebase false

# Handle unrelated histories
git pull origin main --allow-unrelated-histories

SSH Troubleshooting Commands

# Generate new SSH key
ssh-keygen -t ed25519 -C "your-email@example.com"

# Add to SSH agent
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

# View public key
cat ~/.ssh/id_ed25519.pub

Best Practices

1. Authentication Method Selection

• For personal projects: SSH is convenient after initial setup
• For corporate environments: HTTPS often works better with proxy/firewall
• For CI/CD: Use deploy keys or token-based authentication

2. Security Considerations

• Regularly rotate Personal Access Tokens
• Use minimal required permissions for tokens
• Keep SSH private keys secure and backed up

3. Team Workflow

• Document authentication methods used by the team
• Standardize on one method when possible
• Provide clear setup instructions for new team members

Conclusion

The root causes of this problem were multifold:

1. Incorrect remote repository URL - Pointing to wrong user repository
2. Unstable SSH connection - Network environment causing SSH protocol connection failures
3. Unrelated history records - Local and remote repositories created independently, lacking common ancestors

Final Solution:

• Switch to HTTPS protocol for authentication
• Use --allow-unrelated-histories to merge independent histories
• Configure appropriate pull strategy

This systematic troubleshooting and resolution approach can be applied to most Git authentication-related problems.

Additional Resources

• GitHub Documentation - Managing remote repositories
• GitHub Documentation - Connecting to GitHub with SSH
• Git Documentation - Git Credential Storage

This document is based on actual problem-solving process, applicable to macOS and Linux environments. Windows environment commands may vary slightly.