GitHub SSH Key Setup & Personal Access Token (PAT) Authentication Guide

When pushing commits to GitHub or pulling private repositories, authenticating your identity is a required first step.

Since August 2021, GitHub deprecated account password authentication for Git operations. Users attempting to authenticate with passwords receive the error: remote: Support for password authentication was removed on August 13, 2021. The two primary official methods of authentication today are SSH Key Authentication and Personal Access Tokens (PAT).

This guide provides a comprehensive walkthrough for configuring both authentication methods and resolving common connection errors.

1. SSH Key Authentication Setup

SSH (Secure Shell) uses asymmetric cryptographic key pairs. Your private key stays on your local machine while the public key is uploaded to GitHub. Once configured, running git clone [email protected]:... or git push requires no repetitive password prompts.

Step 1: Check for Existing SSH Keys

Open your terminal (Terminal on macOS/Linux, Git Bash or PowerShell on Windows) and run:

ls -la ~/.ssh

If you see files named id_ed25519.pub or id_rsa.pub, you already have an SSH key pair and can proceed directly to Step 3. If the directory does not exist or contains no .pub files, continue to Step 2.

Step 2: Generate a New SSH Key Pair

Recommended Algorithm: We recommend Ed25519, which provides superior cryptographic security and performance over older RSA algorithms. If legacy system compatibility is required, use RSA 4096.

Run the following command (substitute your own registered GitHub email address):

# Recommended: Generate Ed25519 key pair
ssh-keygen -t ed25519 -C "[email protected]"

# Fallback: 4096-bit RSA key pair for legacy operating systems
ssh-keygen -t rsa -b 4096 -C "[email protected]"

The command line will present three sequential prompts:

Enter file in which to save the key (/home/user/.ssh/id_ed25519):
- Press Enter to accept the default file location.
Enter passphrase (empty for no passphrase):
- Press Enter to leave passphrase empty for completely seamless access, or enter a passphrase for additional local key protection.
Enter same passphrase again:
- Press Enter again to confirm.

Step 3: Add Your SSH Public Key to GitHub

Display and copy your public key:
```
# Display Ed25519 public key
cat ~/.ssh/id_ed25519.pub

# Or display RSA public key:
cat ~/.ssh/id_rsa.pub
```
Copy the output string in its entirety (starting with ssh-ed25519 or ssh-rsa and ending with your email address).
Navigate to GitHub in your browser:
- Click your profile photo in the top right -> Settings.
- In the left sidebar, click SSH and GPG keys.
- Click the green button New SSH key.
- Title: Enter a memorable identifier (e.g. MacBook-Pro-Work or Home-Workstation).
- Key type: Keep the default Authentication Key.
- Key: Paste your public key content.
- Click Add SSH key to save.

Step 4: Verify SSH Connectivity

Run the following verification command in your terminal:

ssh -T [email protected]

On your initial connection, you will see a host authenticity verification prompt:

The authenticity of host "github.com (20.205.243.166)" can not be established.
ED25519 key fingerprint is SHA256:+DiY3wvvV6TuKeo9g...
Are you sure you want to continue connecting (yes/no/[fingerprint])?

Type yes and hit Enter.

Upon successful authentication, you will receive GitHub greeting message:

Hi username! You have successfully authenticated, but GitHub does not provide shell access.

Your SSH key is now linked with your GitHub profile.

2. Personal Access Token (PAT) Setup

If you prefer using HTTPS clone URLs (https://github.com/username/repo.git) or operate within CI/CD containers without SSH keys, you must authenticate using a Personal Access Token (PAT) in place of a password.

Step 1: Generate a Personal Access Token

GitHub offers two token variants:

Fine-grained personal access tokens (Recommended): Scoped to specific repositories with granular read/write permissions.
Tokens (classic): Organization-wide access with broad legacy scope compatibility.

Generating a Classic Token:

Go to GitHub -> Settings -> Developer settings (bottom of the left navigation menu).
Select Personal access tokens -> Tokens (classic).
Click Generate new token -> Generate new token (classic).
Fill in the required fields:
- Note: Describe the token intended use (e.g. VSCode-Desktop or Linux-Server).
- Expiration: Select a lifespan (30, 60, 90 days, or custom).
- Select scopes: Check necessary permissions. For standard repository push/pull access, check repo. For GitHub Actions workflow management, check workflow.
Click Generate token at the bottom of the page.
Important: Copy the token immediately (ghp_xxxxxxxxxxxxxxxxxxxx). GitHub will not display this value again after you navigate away.

Step 2: Configure Git Credential Persistence

To avoid manually pasting your token on every Git push, enable local credential caching:

# Windows (Windows Credential Manager)
git config --global credential.helper manager

# macOS (macOS Keychain)
git config --global credential.helper osxkeychain

# Linux (Local credential store)
git config --global credential.helper store

The next time you perform a git push:

Username: Enter your GitHub username.
Password: Paste your generated Personal Access Token (ghp_...).

Git stores these credentials securely, allowing future operations to authenticate automatically.

3. Frequently Encountered Issues & Troubleshooting

Q1: `Permission denied (publickey). fatal: Could not read from remote repository.`

Cause: The local SSH agent has not loaded the key, or permissions on the SSH directory are insecure.
Resolution:

Correct file permissions on Unix-like operating systems:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub

Add your private key to the SSH agent:

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

Q2: Managing Multiple GitHub Accounts (Personal & Work)

Create or edit ~/.ssh/config:

# Personal account
Host github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_personal

# Work account
Host github-work
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_work

When cloning corporate repositories, replace github.com with the configured alias:

git clone git@github-work:company-org/project.git

Q3: HTTPS Git Clone Connection Timeouts

If you experience sluggish download speeds or connection drops over HTTPS when pulling public repositories, accelerate your clone using GH-Proxy:

# Standard clone
git clone https://github.com/torvalds/linux.git

# Accelerated clone via GH-Proxy
git clone https://gh-proxy.org/https://github.com/torvalds/linux.git

For automatic global redirection without manual command edits, see the Git Client Global Configuration.