The push worked yesterday. Today it fails with fatal: Authentication failed for 'https://github.com/...', and nothing you typed changed. What changed is that GitHub stopped accepting your account password for Git operations on 13 August 2021 — and the credential helper on your machine is still faithfully replaying that dead password every time.
This is one of the most common self-inflicted outages in a developer’s week, and it is entirely fixable in about ten minutes. The fix has three moving parts: mint a token that GitHub will actually accept, wire a credential helper to store it so you are not pasting it on every pull, and evict the stale credential the helper keeps handing back. I will cover all three across Linux, macOS and Windows, plus the SSH route for people who would rather not manage tokens at all.
Why it broke, precisely
GitHub announced in 2021 that basic authentication using a username and account password would no longer be accepted for Git operations over HTTPS. The cut-off was 13 August 2021. From that date, the only things GitHub will accept in the password field are a personal access token (PAT) or an OAuth token issued by a credential manager. Your password still logs you into the website; it just does nothing for git push anymore.
Free · 4 minutes
Would you survive contact with a determined attacker — or an auditor?
Fourteen questions on access, patching, detection, and recovery — the basics that prevent most real incidents, and the ones most often assumed rather than verified. Banded finding on screen, full sheet by email.
The reason the error is so confusing is that you rarely see the password prompt. A credential helper cached your password months ago and has been replaying it silently. GitHub only recently stopped accepting it, so the failure surfaces long after the cause. Treat the error as a signal to replace the stored secret, not to re-enter the same one harder.
Step one: mint a fine-grained token
Use a fine-grained personal access token, not a classic one. Classic tokens still work, but they grant a coarse all-or-nothing scope across every repository you can touch — a poor blast radius if the token leaks. A fine-grained token is scoped to named repositories and named permissions, and it carries a mandatory expiry.
In GitHub, go to Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token. Set the resource owner, select only the repositories you actually push to, and grant Contents: Read and write (that is the permission Git operations need). Set a sensible expiry — 90 days is a defensible default. Copy the token now; GitHub will not show it again.
Treat that token as a credential with a lifecycle, the same way you would treat any non-human access. Expiry is a feature: it forces rotation. If a non-expiring surprise is what you are trying to avoid, put a reminder in your calendar a week before the token dies. The discipline here is the same one that governs machine identity generally, a theme I have written about in the context of mutual TLS between services.
Step two: store it in a real credential helper
You do not want to paste the token on every operation, and you certainly do not want it sitting in a plaintext ~/.git-credentials file, which is exactly what the store helper does. Use the operating system’s secret store instead.
On macOS, the keychain helper ships with Git:
# macOS: store credentials in the login keychain
git config --global credential.helper osxkeychain
On Linux, use libsecret so the token lives in the GNOME keyring (or any Secret Service provider) rather than on disk. On Debian and Ubuntu the helper is shipped as source in Git’s contrib directory and needs a one-off build:
# Debian/Ubuntu: build and enable the libsecret helper
sudo apt-get install -y libsecret-1-0 libsecret-1-dev make gcc
sudo make --directory=/usr/share/doc/git/contrib/credential/libsecret
git config --global credential.helper \
/usr/share/doc/git/contrib/credential/libsecret/git-credential-libsecret
On Windows, Git Credential Manager (GCM) is bundled with Git for Windows and is already the default. If it is not set, enable it:
# Windows (and any platform where GCM is installed)
git config --global credential.helper manager
GCM is worth calling out because it is cross-platform and can skip the token dance entirely: on the next push it opens a browser, you authorise through GitHub’s OAuth flow, and GCM stores and silently refreshes the resulting token. For an individual developer that is the least-effort path. For CI, service accounts and headless boxes, a scoped PAT or a deploy key remains the right answer because there is no browser to complete the flow.
With a helper configured, run any authenticating command — git pull is fine. Git prompts for a username (your GitHub handle) and a password. Paste the token into the password field. The helper stores it, and you should not be asked again until the token expires.
Step three: evict the stale credential
Here is the step most write-ups skip, and it is why the error survives an otherwise correct fix. If a helper already holds the dead password, Git keeps offering it and never prompts you for the new token. You have to delete the old entry. The portable way, which works regardless of which helper you configured, is to ask Git itself to reject it:
# Delete any stored github.com credential via the active helper
printf "protocol=https\nhost=github.com\n\n" | git credential reject
If you were using the in-memory cache helper, expire it explicitly with git credential-cache exit. On macOS you can also open Keychain Access, search for github.com and delete the internet password entry by hand if the command route misses it. After the stale entry is gone, the next Git command prompts cleanly and stores the token you actually want.
The SSH alternative, and when to prefer it
If you would rather not manage token expiry at all, switch the remote to SSH. An SSH key does not expire on GitHub’s side, and it never touches the HTTPS password path that broke in the first place. Generate a modern key, add the public half to GitHub, and repoint the remote:
# Generate an Ed25519 key, then add ~/.ssh/id_ed25519.pub
# under GitHub Settings -> SSH and GPG keys
ssh-keygen -t ed25519 -C "you@example.com"
# Verify the key is accepted (expect: "Hi USERNAME! You've successfully authenticated")
ssh -T git@github.com
# Repoint an existing clone from HTTPS to SSH
git remote set-url origin git@github.com:your-org/your-repo.git
SSH is the cleaner choice on a workstation you control. It is a worse choice on a shared or ephemeral machine, where a scoped, short-lived token contained in a keychain is easier to revoke than a key you have to remember to remove. Choose per environment, not per preference.
Make it a policy, not a scramble
This error is trivial once. It becomes a recurring drain when every developer solves it privately, pastes a classic token with full scope because it is the fastest thing that works, and leaves it non-expiring in a plaintext file. In a regulated shop that is an unmanaged, long-lived credential with write access to your source — exactly the sort of access an auditor will ask you to account for. The governance question behind a fatal auth error is the same one behind strong customer authentication: who holds which secret, scoped to what, expiring when. The same care you apply to installing your command-line tooling cleanly belongs on the credentials that tooling uses.
Standardise on fine-grained tokens with a set expiry, or SSH keys for controlled machines, and write down which one your team uses where. The ten-minute fix stops recurring the moment it stops being a personal workaround and becomes the documented default.
Free interactive tool
Website compliance checklist
What your site has to do, based on what it actually does
Answer as much or as little as you like — the list builds as you go. Nothing is stored against your name and no email is required.
Everything that applies
Ordered by what to do first: legal requirements you can close quickly, then larger pieces of work, then what is expected rather than required. Not exhaustive, and not a legal audit.
Dated PDF, yours to keep or circulate.
Most technology problems are not technology problems. They are control problems.
The systems exist. The investment has been made. The question is whether leadership can understand, direct, evidence, and sustain what those systems produce. Find out where control exists — and where it only appears to.