Git Course 0%

Authentication quick-start

Intermediate Git CLI GitLab UI GitHub UI ≈ 10 min

Before this lesson

What you will learn

  • Why your website password does not work for pushing
  • The fastest route: an HTTPS access token stored by the credential helper
  • The alternative: an SSH key, and how to tell which one a repository uses

After this lesson you can

  • I can push to a private repository for the first time without guessing

Why this matters

The first push to a private repository is where most people get stuck, and the error message is unhelpful because it looks like a password problem. It is not. GitLab and GitHub stopped accepting account passwords over Git years ago. This lesson gets you working in ten minutes; Section 8 explains tokens, keys, scopes and expiry properly.

Two routes

HTTPS with an access token SSH with a key pair
URL looks like https://gitlab.com/group/project.git git@gitlab.com:group/project.git
You set up A token on the website, pasted once A key pair on your computer, public half uploaded
Works behind strict company firewalls Usually yes Sometimes blocked
Expiry Tokens expire; you renew them Keys do not expire by default
Best for Getting started today, and most corporate laptops People who push many times a day, on machines they control

Both are equally legitimate. Pick HTTPS if you want to be working in five minutes.

Route 1: HTTPS and an access token

An access token is a long generated string that acts as a password for one purpose, with limited permissions and an expiry date. You create it on the website and paste it once.

  1. Create the token. On GitLab: your avatar → Edit profile → Access → Personal access tokens → Generate token (older versions say Add new token). Fill in Token name, an Expiration date (365 days is the default and usually the maximum), and tick the scopes read_repository and write_repository. On GitHub: avatar → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token, select the repository, and give it the Contents: Read and write permission.
  2. Copy it immediately. Both platforms show the token exactly once. If you lose it, delete it and make another; there is no way to see it again.

  3. Push. Git asks for a username and password:

    Terminal
    $ git push -u origin main
    Username for 'https://gitlab.com': ana
Password for 'https://ana@gitlab.com':

    Type your platform username, and paste the token as the password. Nothing appears as you paste; that is normal. 4. Confirm it was stored. Push again after another commit. If you are not asked a second time, your credential helper saved it (lesson 3.3 set that up: Keychain on macOS, Credential Manager on Windows).

Route 2: SSH and a key pair

An SSH key is a pair of files: a private half that never leaves your computer and a public half you upload to GitLab or GitHub. The server recognizes you by the pair without any password being sent.

Terminal
$ ssh-keygen -t ed25519 -C "ana@northwind-trails.example"
Generating public/private ed25519 key pair.
Your identification has been saved in /Users/you/.ssh/id_ed25519
Your public key has been saved in /Users/you/.ssh/id_ed25519.pub
The key fingerprint is:
SHA256:YMp4KTlbeWOy2ELLvIbfcMl2e0oRPmBhrggl5ND78rg ana@northwind-trails.example

Press Enter at each prompt to accept the default path, and set a passphrase if you want one. Then copy the public half and paste it into the website:

Terminal
$ cat ~/.ssh/id_ed25519.pub

On GitLab: avatar → Edit profile → SSH keys → Add new key. On GitHub: avatar → Settings → SSH and GPG keys → New SSH key. Paste the whole line, starting with ssh-ed25519.

Test it, then use the SSH form of the URL when cloning:

Terminal
$ ssh -T git@gitlab.com
$ git clone git@gitlab.com:northwind-trails/trailguide.git

Which one is this repository using?

Terminal
$ git remote -v

A URL beginning https:// uses a token; one beginning git@ uses a key. Switching an existing clone from one to the other is one command, and no commits are affected:

Terminal
$ git remote set-url origin git@gitlab.com:northwind-trails/trailguide.git

How to do it

The steps above. The one command worth memorizing when something goes wrong:

Terminal
$ git remote -v

It tells you which method the repository expects, which decides whether the problem is a token or a key.

Common mistakes

  • Typing your account password. remote: HTTP Basic: Access denied or Authentication failed. Passwords are not accepted; use a token.
  • A token without the write scope. Cloning works, pushing fails. Check the scopes on the token page; write_repository on GitLab, Contents: Read and write on GitHub.
  • Pasting the private key instead of the .pub file. Delete the key pair, generate a new one, upload only .pub.
  • A stored wrong token. The helper keeps answering with it and the error repeats. Remove the stored entry (lesson 8.4).
  • Mixing the URL forms. An https:// remote will never use your SSH key. git remote -v first.

Try it yourself

Goal: find out how your playground authenticates, and prove the credential is stored.

  1. Run git remote -v and note whether the URL starts with https:// or git@.
  2. Make a small commit and push. Note whether you were asked for anything.
  3. If you were asked, push a second time after another commit; you should not be asked again.

Expected result: an https:// remote asks once and then remembers; a git@ remote asks for the key passphrase at most once per session.

Show solution

Being asked every single time means no credential helper is configured. On macOS git config --global credential.helper osxkeychain, on Windows manager, on Linux libsecret or store. Lesson 8.4 covers each and shows how to remove a wrong entry.

Check yourself

1. git push answers Authentication failed although your password is correct. Why?
2. Which file do you upload to GitLab or GitHub when setting up SSH?
3. Your remote URL begins with https:// and you have an SSH key set up. What happens on push?

Key terms

Remote origin Push Clone

Related