Proving You Are You
GitHub will not let just anyone push to your repository, which means that before your first push you have to prove who you are.
There are two ordinary ways to do it, and typing your account password into the terminal is not one of them. GitHub stopped accepting passwords for Git operations years ago, precisely because a password that can be typed anywhere is a password that gets typed in the wrong place.
Making the account
Choose a username you will be comfortable linking to for years — it appears in every repository URL and every contribution you make. Use the email address you configured in Chapter 1, so that your commits connect to your profile.
If publishing your real address bothers you, GitHub offers a noreply address in the email settings, and you can point user.email at that instead. Either way, the address on your commits is effectively public the moment you push, so make it one you chose deliberately.
Two-factor authentication
Two-factor authentication means a second step at sign-in, usually a code from an app on your phone, so that a stolen password on its own is not enough.
GitHub makes it mandatory for accounts that reach a certain level of contribution — publishing an app or an action, creating a release, contributing to a widely used repository — and strongly recommends it for everyone else. Set it up when you create the account rather than waiting to be told. Save the recovery codes somewhere real. Losing access to your own account in week one is a bad start, and the recovery codes are what prevent it.
Option one: an SSH key
An SSH key is a pair of files: a private key that stays on your machine forever, and a public key that you give to GitHub. GitHub uses the public half to recognize the private half without ever seeing it.
ssh-keygen -t ed25519 -C "you@example.com"
Press Enter to accept the default location. You will be offered a passphrase; taking it means the key on disk is useless to anyone who steals the file.
cat ~/.ssh/id_ed25519.pub
Copy the whole line and paste it into GitHub's SSH key settings. Note the .pub in that filename: it is the public half, the one that is meant to be shared. The file without .pub is the private key, and it never leaves your machine, never goes in a repository, and never gets pasted into anything.
ssh -T git@github.com
GitHub greets you by username and closes the connection. That message is the confirmation; it is supposed to say it does not provide shell access.
Option two: a personal access token
The other route uses HTTPS with a personal access token — a long generated string used in place of a password, with an expiry date and a chosen set of permissions.
You create it in GitHub's developer settings, and it is shown once. Store it in a password manager. When Git asks for a password over HTTPS, the token is what you paste.
A token is a credential exactly like a password, with two advantages: it expires, and it can be revoked from the website without changing anything else about your account. Both advantages disappear the moment you paste it into a file inside your project, which is precisely the accident Chapter 5 was about.
On Sandpiper: you create the account, turn on two-factor authentication, save the recovery codes, add an SSH key, and ssh -T git@github.com answers with your username. Nothing about the project has moved yet — that is the next topic.
Choosing
SSH for a machine you own and will keep using: set it up once and forget it. A token for anything temporary, or where SSH connections are blocked by a network.
Whichever you choose, the URL you use for a repository has to match — an SSH URL for a key, an HTTPS URL for a token. That mismatch is the most common reason a first push fails with an authentication error, and it is the first thing to check.
- "The public key is a secret too." The public half is meant to be shared; that is its entire job. The private half — the file without
.pub— is the secret, and it never leaves the machine. - "A token is safer than a password because it is longer." It is safer because it expires, can be scoped, and can be revoked without disturbing your account. Pasting it into a project file undoes all three.
- "I can use my GitHub password for pushing if I have not enabled 2FA." Password authentication for Git operations was removed for everyone. A key or a token is the only route.
- "Two-factor authentication is something to set up later, once the account matters." GitHub makes it mandatory once your account looks like a contributor's, and an account with push access to real projects is worth stealing on day one.
- Authentication failure is the most common thing that stops a first push, and the error text is unhelpful unless you know which of the two mechanisms you chose.
- "The private key never leaves the machine" is the same instinct that keeps
.envout of the repository in Chapter 5 — one rule, appearing in two places. - Saving the recovery codes is thirty seconds of work against the specific, common disaster of being locked out of your own account.
Knowledge Check
Which half of an SSH key pair do you give to GitHub?
- The public half of the pair, which is the one file whose name ends in
.pub - The private half, so that GitHub can decrypt what your machine sends it
- Both halves, so that GitHub can verify the pair matches when you connect
- Neither — the pair stays local and GitHub verifies it through your password
Why will your GitHub account password not work for pushing?
- GitHub removed password authentication for Git operations some years ago
- Passwords work only for repositories you own, not for ones shared with you
- Passwords work only when two-factor authentication has not been enabled
- Passwords work but must be typed into the website rather than the terminal
What are the two practical advantages of an access token over a password?
- It expires on its own, and it can be revoked without touching your account
- It is longer, and it cannot be guessed by anyone trying common passwords
- It works from any machine, and it does not need to be stored anywhere at all
- It is unique per repository, so a leak affects only one project at a time
Your first push fails with an authentication error. What is the first thing to check?
- Whether the repository's URL form matches the method you set up
- Whether your account password was typed correctly at the prompt
- Whether the repository has been made public rather than left private
- Whether your two-factor codes are being generated with the right time zone
You got correct