Encountering a "git push origin main authentication failed" error is a rite of passage for almost every developer using Git. It typically strikes at the worst possible moment—right after you have finished a feature, committed your changes, and are ready to share your work with the team. The error message itself is often vague, leaving you staring at the terminal wondering if your code is broken, your account is locked, or if the internet is down.
The reality is usually much simpler: Git is telling you that the remote server (GitHub, GitLab, Bitbucket, or Azure DevOps) does not recognize the credentials you provided. Since Git is a distributed version control system, it relies entirely on the hosting provider to verify your identity before accepting new commits. Understanding why this verification fails is the key to fixing it permanently.
The Root Causes: Why Authentication Fails
Before jumping into solutions, it helps to categorize the problem. Authentication failures generally fall into three distinct buckets. Identifying which bucket you are in will save you hours of trial and error.
1. The Death of Password Authentication (The Most Common Cause)
If you are using GitHub, GitLab, or Bitbucket, password authentication for Git operations was deprecated years ago. As of August 2021, GitHub requires a Personal Access Token (PAT) or an SSH key for command-line operations. If you are typing your actual account password when prompted, the server will reject it with an authentication failed error. This is the number one reason developers encounter this issue today.
2. Credential Manager Issues (Cached Credentials)
Operating systems and Git itself often cache credentials to save you from typing them repeatedly. Tools like Git Credential Manager (GCM), osxkeychain (macOS), or the Windows Credential Manager store your tokens. If you recently changed your password, revoked a token, or enabled Two-Factor Authentication (2FA), the cached token becomes invalid. Git keeps trying the old, stale token, resulting in a loop of failures Simple, but easy to overlook. And it works..
3. SSH Key Misconfiguration
For developers using the SSH protocol (git@github.com:user/repo.git), the failure usually stems from the SSH agent not running, the key not being added to the agent (ssh-add), the public key not being added to the hosting provider's settings, or a mismatch between the key used and the key registered Took long enough..
Solution Path 1: Switching to HTTPS with a Personal Access Token (PAT)
This is the standard, recommended workflow for most modern workflows, especially if you are behind a corporate firewall that blocks SSH ports.
Step 1: Generate a Personal Access Token
You cannot use your login password. You must generate a token with specific scopes That's the part that actually makes a difference..
For GitHub:
- Go to Settings > Developer settings > Personal access tokens > Tokens (classic) (or "Fine-grained tokens" for more security).
- Click Generate new token.
- Give it a descriptive name (e.g., "My Laptop CLI Access").
- Set an expiration date (90 days is standard practice; rotate them regularly).
- Crucial Step: Select scopes. For pushing code, you need at minimum
repo(full control of private repositories) andworkflow(if you use GitHub Actions). - Copy the token immediately. You will not see it again.
For GitLab:
- Go to Preferences > Access Tokens.
- Create a token with
write_repositoryandread_repositoryscopes.
Step 2: Update Your Local Git Configuration
When you next run git push origin main, Git will prompt for a username and password Worth keeping that in mind..
- Username: Your GitHub/GitLab username (or email).
- Password: Paste the PAT you just copied. Do not type your account password.
Step 3: Clear Stale Credentials (If it still fails)
If you have pushed before, your OS Keychain likely holds the old password. You must evict it That's the part that actually makes a difference..
macOS:
git credential-osxkeychain erase
host=github.com
protocol=https
# Press Enter/Return twice
Alternatively, open Keychain Access (Cmd+Space > Keychain Access), search for github.com, and delete the "Internet Password" entries.
Windows:
Open Credential Manager (Control Panel > User Accounts > Credential Manager > Windows Credentials). Look under Generic Credentials for git:https://github.com and click Remove Worth keeping that in mind..
Linux (using libsecret/gnome-keyring):
git credential-libsecret erase
# Follow prompts or use a GUI like "Passwords and Keys" (Seahorse)
Solution Path 2: The SSH Workflow (Preferred for Automation)
SSH is often preferred because it separates your authentication from your account password/token rotation. Once set up correctly, it "just works" across token expirations.
Step 1: Check for Existing Keys
Run ls -al ~/.ssh. Look for files like id_ed25519 and id_ed25519.pub (modern standard) or id_rsa and id_rsa.pub (older RSA standard).
Step 2: Generate a New Key (If needed)
If you don't have keys, or want a dedicated one:
ssh-keygen -t ed25519 -C "your_email@example.com"
# Press Enter to accept default file location
# Enter a strong passphrase (highly recommended)
Step 3: Start the SSH Agent and Add Key
The agent holds your decrypted key in memory so you don't type the passphrase every push.
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
On macOS, add --apple-use-keychain to ssh-add to store the passphrase in Keychain. On Windows (Git Bash), ensure the ssh-agent service is running (Services.msc > OpenSSH Authentication Agent > Automatic).
Step 4: Add Public Key to Provider
Copy the public key content:
cat ~/.ssh/id_ed25519.pub
# Copy the output starting with ssh-ed25519...
Paste this into GitHub Settings > SSH and GPG Keys > New SSH Key (or GitLab Preferences > SSH Keys) The details matter here..
Step 5: Verify Connection
ssh -T git@github.com
# You should see: "Hi username! You've successfully authenticated..."
Step 6: Update Remote URL (Critical)
If your repo was cloned via HTTPS, the remote URL looks like https://github.com/user/repo.git. SSH requires a different format. Update it:
git remote set-url origin git@github.com:username/repository.git
Verify with git remote -v. Now git push origin main will use SSH keys automatically.
Solution Path 3: Git Credential Manager (GCM) – The "Set and Forget" Way
Modern Git installations (Git for Windows, Git via Homebrew on Mac) ship with Git Credential Manager (GCM). This is a cross-platform credential helper that handles the complex OAuth flows, 2FA prompts, and token storage securely in your OS keychain Most people skip this — try not to..
How to Ensure GCM is Active
Run:
git config --global credential.helper
- macOS: Should return
osxkeychain(legacy) ormanager-core(GCM). - Windows: Should return
manager-core. - Linux: Should return
manager-coreorlibsecret.
If it returns nothing or cache/store (insecure plain text), configure GCM:
git config --global credential.helper manager-core