GitHub Authentication
Choose a transport, store credentials safely, and recover from auth failures without pasting tokens into the repository.
Authentication is not commit identity
Git Installation set user.name and user.email. Those strings are written into commits. They do not log you into GitHub. Git Remote taught fetch and push against any location, including a folder. This lesson is the extra proof GitHub requires when that location is a GitHub HTTPS or SSH URL.
Who authored the commit
user.name and user.email label history. They work offline. GitHub never sees them until a push succeeds.
Who may talk to the host
A credential helper, GitHub CLI session, SSH key, or scoped token proves the account. Failure here leaves local commits intact.
Choose HTTPS or SSH, then one URL
Both methods reach the same GitHub repository. Pick one, verify it, and keep the remote URL in that form. Mixing an SSH remote with HTTPS tokens, or the reverse, produces confusing failures that look like Git bugs.
HTTPS
Shortest setup for many beginners. Git Credential Manager or GitHub CLI stores a token. The URL starts with https://github.com/.
SSH
Durable key-based terminal workflow. A private key stays on the machine; the public key is added to GitHub. The URL looks like git@github.com:OWNER/REPOSITORY.git.
One method first
Teams sometimes standardize. Use what the project documents. You can switch later with git remote set-url.
Organization policy
Some employers require SSO-authorized tokens or hardware keys. Follow that policy instead of a personal shortcut.
# HTTPS remote
https://github.com/OWNER/REPOSITORY.git
git remote add origin https://github.com/OWNER/REPOSITORY.git
git remote -v# SSH remote
git@github.com:OWNER/REPOSITORY.git
git remote add origin git@github.com:OWNER/REPOSITORY.git
git remote -vTest what you learned
Does an HTTPS GitHub remote URL start with https://github.com/ or git@github.com:?
HTTPS uses a helper, not a password
# Shortest common setup: GitHub CLI talks to a credential helper
gh auth login
gh auth status
# Git will then ask the helper when it talks to an HTTPS remote
git ls-remote originGitHub CLI is optional. gh auth login can open a browser, request permissions you should actually read, and configure Git to use the resulting credentials. gh auth status reports which account the CLI will use. On Windows, Git Credential Manager is often already present. macOS and Linux can use a supported helper or the same CLI flow.
A personal access token is a last-resort HTTPS credential when a tool specifically requires one. Create it on GitHub with the smallest scope, a short expiry, and a note naming the device. Paste it into a credential prompt or helper—not into .git/config, not into a shell history you will commit, and not into a README.
Platform-specific installer and helper details live in the Git and GitHub setup guide.
SSH uses a public and private key pair
ls -al ~/.ssh
ssh-keygen -t ed25519 -C "you@example.com"
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
cat ~/.ssh/id_ed25519.pub
# After the public key is on GitHub:
ssh -T git@github.comGenerate an Ed25519 key unless your organization documents another type. Protect the private key with a passphrase and load it into the agent. Copy only id_ed25519.pub into GitHub Settings → SSH and GPG keys, with a title that names this computer.
ssh -T git@github.com tests the GitHub SSH user. The username in that command is git, not your GitHub handle. A successful test still prints a message that looks like a warning; read it. Failure with Permission denied (publickey) means the client did not offer a key GitHub has on file.
Test what you learned
Type the command that tests SSH authentication to GitHub as the git user.
If that command already fails, use the Permission denied (publickey) guide instead of reinstalling Git.
Match the remote URL to the method
# Switch an existing origin to SSH after the key works
git remote set-url origin git@github.com:OWNER/REPOSITORY.git
git remote -v
# Or switch to HTTPS
git remote set-url origin https://github.com/OWNER/REPOSITORY.gitAfter you change the URL, git remote -v should show the protocol you actually configured. Fetch or git ls-remote origin then proves GitHub accepts it. Do not create a GitHub repository in this lesson; a public clone or a later empty repo both use the same authentication.
Test what you learned
Type the command that points origin at git@github.com:OWNER/REPOSITORY.git.
Diagnose auth failures by protocol
Authentication failed
- Read
git remote -vand confirm anhttps://URL. - Check
gh auth statusor the credential manager account. - Do not retry the website password.
- Expired or SSO-unauthorized tokens fail the same way.
Permission denied (publickey)
- Confirm a
git@github.com:remote. - Run
ssh -T git@github.comand, if needed,ssh -vT git@github.com. - Check which keys the agent loaded and which
sshGit uses. - Confirm the matching public key is on the intended GitHub account.
If fetch works and push is denied, authentication may already have succeeded. Hosted permissions, branch protection, or a missing write grant are then GitHub policy—not a broken SSH key. Leave those for later repository and protection lessons.
Never commit tokens or private keys
A token or private key that enters a commit is published to every clone of that history. Deleting the file later does not remove the bytes from older snapshots. Git .gitignore keeps .env noise out; it cannot un-publish a secret that was already committed.
- 01Revoke first
On GitHub, revoke the token or delete the exposed SSH key. Assume the old secret is burned.
- 02Rotate
Create a replacement with the smallest scope and a device-specific note.
- 03Search history
Treat every clone, CI log, and backup as a possible remaining copy.
- 04Keep secrets out of Git
Store tokens in a credential helper or agent. Never paste them into source files or commit messages.
Guided practice: prove one method
- 01Pick HTTPS or SSH
One method. Write down the URL form that matches it.
- 02Configure the credential
Run
gh auth loginor generate and add an SSH key. Do not paste a token into a file inside a repository. - 03Prove the host
HTTPS:
gh auth status. SSH:ssh -T git@github.com. - 04Inspect a remote URL
On any clone, run
git remote -vand confirm the protocol matches the method you just proved. - 05Switch only if needed
If the URL is the other protocol,
git remote set-url originto the matching form, thengit ls-remote origin.
Independent lab: authenticated remote report
- Choose HTTPS or SSH. Do not configure both in this lab.
- Prove the method with
gh auth statusorssh -T git@github.com. Record the success evidence, not any token or private key. - Inspect
git remote -von a disposable clone. If the URL protocol does not match, change it withgit remote set-url origin. - Run
git ls-remote originand explain whether the result is an auth success, a permission policy, or a missing repository. - Write four lines you would give a teammate: method, URL form, test command, and what you will never commit.
Common authentication mistakes
Using the website password
Git operations reject it. Use a helper, CLI, SSH, or a scoped token.
Pasting the private key into GitHub
Only the .pub file belongs in SSH settings.
HTTPS credentials against an SSH URL
Change the remote with git remote set-url instead of retrying the other secret.
Committing a token to “save it”
History copies the secret. Helpers and agents exist so Git never needs that file.
Lesson review
You can separate commit identity from GitHub login, pick HTTPS or SSH, match the remote URL, and treat leaked credentials as an incident. The next lesson creates the hosted repository those credentials will talk to.
- I know
user.emaildoes not authenticate GitHub. - I can choose HTTPS (
https://github.com/) or SSH (git@github.com:) and keep the remote URL in that form. - I can prove the method with
gh auth statusorssh -T git@github.com. - I rotate leaked tokens and never commit private keys.