Proving You Are Allowed to Push

For years you could push over HTTPS by typing your GitHub username and password. In August 2021 that was switched off entirely, and the replacement error is misleading.

remote: Support for password authentication was removed on August 13, 2021.remote: Please see https://docs.github.com/get-started/getting-started-with-git/        about-remote-repositories#cloning-with-https-urls for information on        currently recommended modes of authentication.fatal: Authentication failed for 'https://github.com/you/project.git/'

"Authentication failed" sounds like a wrong password, so people carefully retype the correct one and it fails again. It is not wrong; that method no longer exists. You need one of two things: a personal access token, which is used in place of a password over HTTPS, or an SSH key, which changes the protocol entirely.

A personal access token is a long random string you use where a password used to go. It is better than a password in two specific ways: it can be limited to certain permissions, and it can be set to die on a date.

1. 1

   Settings → Developer settings → Personal access tokens

   It is at the very bottom of the settings sidebar, which is hard to find the first time.

2. 2

   Choose fine-grained, not classic

   Fine-grained tokens are scoped to specific repositories and specific permissions. A classic token with the repo scope can read and write every repository you have access to, including your employer's.

3. 3

   Set an expiry

   Ninety days is a reasonable default. "No expiration" means a string that grants access to your account forever, sitting in a file on a laptop.

4. 4

   Copy it now

   GitHub shows the value exactly once. Close the tab and it is unrecoverable — you generate a new one and delete the old.

5. 5

   Use it as the password when Git asks

   Username is your GitHub username; password is the token. Nothing else changes.

SSH uses a key pair: a private key that stays on your machine and a public key you give to GitHub. Authenticating proves you hold the private key without ever sending it, so there is no secret in transit for anybody to capture.

# 1. Generate a key pair. Ed25519 is the current recommendation.$ ssh-keygen -t ed25519 -C "[email protected]"# Press Enter for the default path. SET A PASSPHRASE. # 2. Start the agent and add the key so the passphrase is asked for once$ eval "$(ssh-agent -s)"$ ssh-add ~/.ssh/id_ed25519 # 3. Copy the PUBLIC key — the one ending .pub$ cat ~/.ssh/id_ed25519.pub          # macOS/Linux# Paste it into GitHub: Settings -> SSH and GPG keys -> New SSH key # 4. Check it worked$ ssh -T [email protected]# Hi you! You've successfully authenticated, but GitHub does not provide shell access.

If you cloned over HTTPS and want to switch, you do not need to re-clone. Change the URL:

$ git remote set-url origin [email protected]:you/project.git$ git remote -v      # confirm it now starts git@ rather than https://

One organisational detail matters early: if your employer uses SAML single sign-on, both tokens and SSH keys must be separately authorised for that organisation after being created. A key that works fine for your own repositories will fail on the company one until you click that button, and the error does not mention SAML.

GitHub's official command-line tool handles these steps interactively, including generating an SSH key and uploading it for you.

# Install$ brew install gh              # macOS$ winget install --id GitHub.cli   # Windows$ sudo apt install gh          # Debian/Ubuntu # Authenticate — it opens a browser and handles everything$ gh auth login # Check$ gh auth status

This is the shortest correct path for a new machine, and it is what to recommend to somebody who is stuck. It is also useful well beyond authentication:

$ gh repo clone you/project        # clone with the right protocol already configured$ gh repo create my-thing --public --source=. --push$ gh pr create --fill              # open a pull request from the current branch$ gh pr checks                     # see whether CI passed, without a browser$ gh pr view --web                 # open it in a browser when you do want one$ gh issue list --assignee @me

Git does not ask for a token on every push, because a credential helper stores it. That is a convenience, and it is also why a rotated token keeps failing with the old value long after you replaced it.

# Which helper is in use$ git config --get credential.helper # Forget what is stored for GitHub, so the next push asks again$ git credential reject$ protocol=https$ host=github.com# (then press Enter on a blank line) # macOS, the direct route$ security delete-internet-password -s github.com