Ana has her remote registered. She types git push origin main full of enthusiasm and gets this:

A prompt waiting for something she is not quite sure about. And if she types the password she uses to log into the web interface, she will very likely get a rejection along the lines of Support for password authentication was removed.

This wall stops a lot of people on their first contact with a remote repository, and it is a shame, because the problem has nothing to do with Git: it is a problem of identity. Registering a URL does not grant permission to write to it. Somebody has to prove to the server that they are who they claim to be.

This lesson takes that wall down once and for all. We will see why cloning a public repository asks for nothing while pushing does, the two authentication mechanisms in use today — tokens over HTTPS and SSH keys —, how to generate a key with ssh-keygen, and how to make the operating system remember your credentials so that you do not type them forty times a day. It is the lesson Carla needs before writing her first line, because she is coming in from Windows 11 and the credential manager works differently there.

1. Why a public clone asks for nothing and a push does
2. Authentication versus authorisation
3. HTTPS with a personal access token
4. SSH: the key pair
5. Generating the key with ssh-keygen -t ed25519
6. Uploading the public key, testing the connection and using the agent
7. ~/.ssh/config: several identities on the same machine
8. HTTPS versus SSH: a comparison table
9. Credential managers by operating system
10. Typical errors and how to diagnose them

The answer is simple and clears up a great deal of confusion: they are operations with different permission requirements.

A public repository is, by definition, readable by anybody. Downloading the code of an open project requires no identification, in the same way that reading a web page requires no account.

Writing is another story. When you push, you are asking the server to modify its references: to make refs/heads/main point at a different commit. That changes what everyone will see when they clone from that moment on. No sensible server allows a stranger to do that.

And there is a subtlety that surprises a lot of people: your Git identity and your server identity are different things.

What you configured back in lesson 01-06 is commit metadata: text recorded inside the object and shown by git log. It authenticates nothing. Anyone can put any name and any address into their commits; Git does not verify it.

Authentication happens at another layer: at the transport layer, when your Git talks to the server. These are two independent identities, and mixing them up is a bad idea:

(There is a way to link the two for real, by signing commits cryptographically. That is a security topic and it is covered in lesson 08-05.)

Two words that get confused daily and that produce very different errors:

• Authentication: who you are. Proving your identity to the server.
• Authorisation: what you may do. The permissions that identity holds over that particular repository.

You can be perfectly authenticated and still be turned away:

Look at the message: the server knows you are Carla. Authentication worked. What fails is authorisation: Carla has not been given write access to that repository, or her token lacks the necessary scope.

Telling the two cases apart saves a lot of time:

That last case is especially treacherous: Repository not found does not necessarily mean you mistyped the URL. It can mean "it exists, but not for you".

A personal access token (PAT) is a long string generated by the platform that works as a password for one specific purpose. It looks something like this (fictitious, obviously):

For years, HTTPS authentication used the account's username and password. GitHub withdrew that option in August 2021 and the other platforms followed suit. The reasons are solid:

• Limited scope. Your password opens the whole account: repositories, settings, billing, deletion. A token can grant read-only access to one specific repository.
• Individually revocable. If a token leaks, you delete it and only what used it breaks. Changing the password forces you to reconfigure everything.
• Compatible with two-factor authentication. If your account has a second factor, there is no way to enter it at a Git prompt. The token resolves that dead end.
• Expiry. A token can expire in 30, 60 or 90 days; a password lives until somebody remembers to change it.
• Auditable. The platform records which token did what and when it was last used.

The exact procedure varies by platform, but the shape is always the same: account settings → access tokens → create → choose a name, an expiry and some scopes.

Scopes are the important part. Grant the bare minimum:

What you almost never need: administration scopes, user-management scopes, repository-deletion scopes or access to the organisation's settings. A deployment token whose only job is to clone should not be able to delete anything.

One operational tip: create one token per machine, rather than one shared between your laptop, your home computer and the continuous integration server. If you lose the laptop, you revoke that token and everything else keeps working.

The token goes where the password would go:

The token goes at that second prompt, not the account password. Since it is not echoed as you type, pasting it from the clipboard is the convenient route.

What you must never do is embed it in the URL:

That token ends up written in plain text in .git/config, appears in your shell history, sneaks into screenshots and shows up in any git remote -v you run in front of somebody. That is what the credential managers in section 9 are for.

The alternative to HTTPS is SSH, and it rests on a different concept: instead of a shared secret, it uses an asymmetric key pair.

• The private key (~/.ssh/id_ed25519) stays on your machine and never leaves it. It is the equivalent of your physical key.
• The public key (~/.ssh/id_ed25519.pub) is uploaded to the server. It is the equivalent of the lock: it can be handed around without risk.

The mathematical property that makes it work is that whatever the public key verifies can only have been produced by the private one, and the private one cannot be derived from the public one.

The advantage over the token is plain: the secret never travels over the network. Not even encrypted. All that is transmitted is a signature over a different piece of random data on every connection, useless to an attacker who captures it.

Use Ed25519 unless you run into an old server that rejects it, in which case rsa with 4096 bits.

Carla, on her Windows 11 machine, opens Git Bash (which she installed in lesson 01-02 and which ships with all the OpenSSH tools). The commands are identical on Linux, macOS and Git Bash:

A breakdown of the options:

• -t ed25519: the key type. This is the argument that matters.
• -C "…": a comment appended to the end of the public key. It helps you identify the key in the server's list once you have four keys from four machines. It can be your email address, but something like "carla-windows-laptop" is even better, because what you want to know is which machine that key belongs to.

The dialogue:

Press Enter to accept the default path. Only change it if you are going to have several keys, a case we will look at in section 7.

This is where you should stop and think. The passphrase encrypts the private key on disk. If somebody steals your laptop or copies the file, the key is useless to them without it.

Set one. With ssh-agent, the real cost is typing it once when you boot the computer.

The result:

Two files. Let us see what they hold:

Look at the permissions, which are part of the security mechanism:

• The private key is -rw------- (600): only you can read it. With more open permissions, OpenSSH would refuse to use it.
• The public key is -rw-r--r-- (644): readable by anybody, and that is fine.

Three parts: the type, the key itself and the comment. This line is what gets uploaded to the server, and it can be published without any risk at all.

And the private one, with the obvious warning:

This content is not shown, not copied and not sent to anybody. Ever. Not to a colleague, not to technical support, not pasted into a chat. If you are ever unsure which of the two files to upload, the rule never fails: the one ending in .pub.

You copy the contents of the .pub file and paste it into the platform (account settings → SSH keys → new key). To get it onto the clipboard:

A common warning: no line break must survive in the middle when you paste. The key is one single long line; if the editor breaks it, it will not work.

Before attempting any Git command, check that the channel works:

The -T option means "I do not want an interactive terminal": I am only checking authentication.

The first time, this appears:

Do not answer yes out of habit. That message is telling you your computer does not know that server yet and is asking you to confirm it is the genuine one. Platforms publish their fingerprints in their documentation; compare before accepting. It is your only defence against a man-in-the-middle attack on that first connection.

Once accepted, the fingerprint is stored in ~/.ssh/known_hosts and you will not be asked again.

If all goes well:

That message is a complete success, even though it says shell access is not provided. That is exactly what should happen: the git user on a repository server is not there to open a session, only to speak Git.

With a passphrase, every operation would ask for the phrase. The agent keeps it in memory for the session and answers on your behalf.

From here on, every push and pull works without typing anything.

Each system has its own way of automating this:

On Windows 11, the ssh-agent service ships with the system but starts out disabled. From PowerShell as administrator:

And then, from Git Bash:

One detail for Carla: if she uses Git Bash's ssh together with the system agent, the two may not see each other. The simple fix is to use the ~/.bashrc block above, which starts an agent of Git Bash's own.

A very real situation, and precisely Carla's: in lesson 01-05 we saw that she works in two contexts, the example.com one and another company's, with different email addresses. If each of them also requires a separate account and a separate key, SSH has to be told which one to use in each case.

That is solved in ~/.ssh/config:

An explanation of each directive:

IdentitiesOnly yes deserves a comment, because it heads off a baffling failure. Without it, SSH offers all your keys one after another until one works; if you have five, the server may cut the connection for too many attempts and you get a Too many authentication failures that looks entirely unrelated to the real cause.

The invented alias trick is what makes this file powerful. Look at Host git-othercompany: that name exists in no DNS anywhere. But Carla can now write:

And SSH translates git-othercompany into git.othercompany.example with the right key. The same mechanism handles two accounts on the same platform, the classic case of a personal account and a work account on the same GitHub:

Same real server, two identities, with no ambiguity at all.

And to check which key will actually be used:

The -v (verbose) option is the definitive diagnostic tool for any SSH problem.

File permissions, which are strict here too:

Both options are valid and both are used on a massive scale. The choice depends on the context:

• Everyday work machine, always the same account → SSH. Configure it once and forget it: it does not expire, it does not need renewing and it does not interrupt.
• Corporate network with port 22 closed → HTTPS + token. (Some platforms offer SSH over port 443 as an alternative.)
• Continuous integration, containers, servers → a token with the minimum scope and a short expiry, or a read-only deployment key.
• Cloning a public project to read it → HTTPS with no credentials.
• Several accounts on the same machine → SSH with ~/.ssh/config.

And one reassuring fact: switching from one to the other is a set-url, as we saw in the previous lesson:

You lose nothing: the commits are the same, the references are the same and only the route changes.

With HTTPS one practical problem remains: nobody is going to type a 40-character token on every push. That is what credential.helper is for, which already appeared in lesson 01-06 and which we can now understand fully.

A credential helper is an external program that Git asks "do you have credentials for this server?" before showing the prompt, and tells "store these" when access works.

Linux (Ana, Ubuntu) — libsecret

It integrates with the desktop keyring (GNOME Keyring, KWallet), which stores secrets encrypted and unlocks with your session:

On some distributions it comes precompiled and installing the relevant package is enough.

macOS (Bruno) — osxkeychain

It is included with Git on macOS; a single line:

Credentials are stored in the Keychain, encrypted and visible in the Keychain Access application, where they can be reviewed and deleted.

Windows 11 (Carla) — Git Credential Manager

This is the most interesting case, which is why we left it for last. GCM installs alongside Git for Windows and is configured by default:

What GCM does goes beyond storing a string:

• It stores credentials in the Windows Credential Manager, encrypted with your system user account.
• It opens a browser window to authenticate against GitHub, GitLab or Azure DevOps, with support for two-factor authentication.
• It can generate and renew tokens by itself, so Carla does not have to create any by hand.
• It is cross-platform: it also exists for Linux and macOS, although on those systems the native ones are usually enough.

For Carla this means her first git clone of a private repository will open a browser window, she will log in with her account and her second factor, and from then on she will never see a prompt again. It is by far the smoothest experience of the three.

If she wants to check what is stored, she can open it from Git Bash:

Git's entries appear in the "Generic Credentials" section with the git: prefix.

It is tempting because it is so easy:

And it works first time. The problem becomes obvious when you look at the file it creates:

Your token, legible, in a file in your home folder. Unencrypted, with no master password and no expiry. The permissions are 600, which protects it from other users of the same machine, but not from:

• Any program running as your user, including a malicious dependency of your project.
• A backup of your home folder that ends up on an external drive or in the cloud.
• Somebody booting the computer from a USB stick or pulling the disk out.
• A configuration file synchronised between machines by mistake.

When not to use it: on your laptop, on your desktop computer, on any machine with access to repositories that matter.

When it might make sense: on an ephemeral container or a disposable, isolated virtual machine, with a read-only token that expires in hours, where no keyring is available and the machine's lifetime is shorter than the token's. Even there, a better option almost always exists.

The reasonable alternative when there is no keyring is cache, which keeps credentials in memory for a limited time:

An hour without typing anything again, and nothing touching the disk. When you shut down, it is gone.

Everything to do with secret management, commit signing and handling credentials leaked into the history is developed in lesson 08-05. Here we have dealt with the operational side: being able to work comfortably without leaving secrets lying around.

This is the most common SSH error. It means: "The server did not accept any of the keys you offered it." The causes, in order of frequency:

If it answers Could not open a connection to your authentication agent, the agent is not running:

If it answers The agent has no identities, it is running but empty: the ssh-add is missing.

Compare that fingerprint with the one the platform shows in its list of keys. If they do not match, you uploaded a different one.

OpenSSH silently ignores private keys with permissions that are too open, which produces this error with no clue whatsoever.

In the output you will see which keys it offers (Offering public key:) and how the server responds. It is the quickest way to discover you are offering the wrong key.

It means the server's key does not match the one you had stored in ~/.ssh/known_hosts. There are two possible explanations:

1. Legitimate: the server has been reinstalled or migrated, or the platform has rotated its keys (which happens now and then and is always announced publicly).
2. A man-in-the-middle attack: somebody is impersonating the server.

Do not delete the entry without checking. The correct procedure:

The mild variant of the same warning — The authenticity of host … can't be established — is the first connection: nothing is stored yet. There too it is worth comparing the fingerprint before accepting.

And one command that settles the "I do not know which credential Git is using" question:

It shows the whole process, including which credential helper gets invoked. Use it only for debugging and do not share its output without reviewing it, because it can include sensitive headers.

Mistake 1: uploading the private key instead of the public one. It happens more than you would think. The rule is simple: you upload the file ending in .pub. If you have uploaded the private one by mistake, delete it from the server, remove the whole pair from your disk and generate a new one: that key is compromised for good.

Mistake 2: embedding the token in the remote's URL. It ends up in .git/config, in your shell history and in every screenshot. Use a credential manager.

Mistake 3: creating the key with no passphrase "to save time". A stolen laptop stops being a hardware problem and becomes a problem of access to all your repositories. With ssh-agent, the passphrase is typed once per session.

Mistake 4: confusing user.email with your access identity. Changing user.email fixes no authentication problem: it only changes the text shown in commits. They are different layers.

Mistake 5: accepting the server's fingerprint without looking at it. That prompt on the first connection is your only chance to spot an impersonation. Platforms publish their fingerprints; comparing them takes ten seconds.

Mistake 6: using the same token on five machines. When the time comes to revoke it, all five break at once and you will not know which one leaked. One token per machine and per purpose.

Mistake 7: reaching for credential.helper store by default. It leaves the token in plain text in your home folder. Use your system's native manager, or cache if none is available.

Tip 1: always test with ssh -T before blaming Git. If ssh -T git@server works, the problem is not in SSH. If it does not, ssh -vT tells you exactly which step fails.

Tip 2: put a useful comment on the key. -C "carla-windows-laptop" is infinitely more practical than an email address when, a year from now, you see four keys in the server's list and have to decide which one to revoke.

Tip 3: note down when your tokens expire. A token that expires on a Monday morning produces half an hour of bewilderment. Set yourself a reminder a few days beforehand.

Tip 4: IdentitiesOnly yes whenever you have more than one key. It avoids Too many authentication failures, one of the errors hardest to connect with its cause.

Tip 5: for automation, minimum scope and short expiry. A continuous integration token whose only job is to clone needs neither write nor administration permission.

Without uploading anything to any server:

1. Generate an Ed25519 pair at a specific path, ~/.ssh/course_practice, with a descriptive comment.
2. Show the permissions of both files and explain why they differ.
3. Show the public key's fingerprint.
4. Load it into ssh-agent and verify that it is listed.
5. Check that the fingerprint of the private key and that of the public one match. Explain why.
6. Unload it from the agent and delete the files.

Carla needs to work with two accounts: the team's (git.example.com) and another company's (git.othercompany.example).

1. Write the complete ~/.ssh/config for both, with separate keys.
2. Explain what each directive does.
3. Write the clone URL she would use for each repository.
4. Give the command that would let her check which specific key is offered to each server.
5. Explain what would happen if she left out IdentitiesOnly yes and had six keys loaded.

For each of these messages, state: (a) whether the failure is one of authentication or of authorisation, (b) the two most likely causes and (c) the command or check you would start with.

1. [email protected]: Permission denied (publickey).
2. remote: Permission to team/task-manager.git denied to carla.
3. remote: Support for password authentication was removed.
4. WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!
5. ssh: connect to host git.example.com port 22: Connection timed out

Solution 1:

The -f option fixes the path and skips the "where shall I save it" dialogue.

The private one is 600: only its owner can read it, and OpenSSH refuses to use it with laxer permissions, because any other user on the system could copy it. The public one is 644 because it is designed to be handed around: it reveals nothing exploitable.

Identical, and that is no accident. The fingerprint is a hash of the public key, and the public key can be derived from the private one (not the other way round). When ssh-keygen -lf is handed a private key, it extracts the public one and computes its fingerprint. That is why the fingerprint lets you match, without ambiguity, which private key on your disk corresponds to which public key on the server: it is exactly the check from section 10.

Solution 2:

1. The ~/.ssh/config file:

2. What each directive does:

• Host: the name Carla types in the URL. In the first block it matches the real server; in the second it is an invented alias that exists in no DNS.
• HostName: the real server to connect to. This is what resolves the alias.
• User git: the SSH user. On repository platforms it is always git; the real user is worked out from the key you present.
• IdentityFile: which private key to use with this destination.
• IdentitiesOnly yes: use only that key, without offering the others.
• AddKeysToAgent yes: load it into the agent on first use, to avoid repeating the passphrase.

3. The clone URLs:

4. Checking which key is offered:

Each destination receives exactly one key, its own.

5. Without IdentitiesOnly yes: SSH would offer every key loaded in the agent, one by one, in an order you do not control. With six keys and a server whose MaxAuthTries is 6 (the usual value), it is very likely to run out of attempts before reaching the right one:

An especially treacherous error, because the right key exists and is loaded: SSH simply never got round to trying it. On top of that, offering all your keys to every server you talk to is an unnecessary information leak: you reveal how many identities you have.

Solution 3:

1. Permission denied (publickey)

• (a) Authentication. The server accepted no key at all: it does not even know who you are.
• (b) The key is not loaded in the agent, or the one on your disk is not the one uploaded to the server. Less frequent but very disorienting: permissions too open on the private key, making OpenSSH ignore it silently.
• (c) ssh-add -l to see what is loaded and, if that clears nothing up, ssh -vT [email protected] to see which key is offered and how the server responds.

2. Permission to team/task-manager.git denied to carla

• (a) Authorisation. The message names Carla, so authentication worked perfectly.
• (b) Her account has no write access to that repository, or — if she is going over HTTPS with a token — the token lacks the write scope.
• (c) Review the account's permissions in the repository settings and the token's scopes on the platform. No Git command fixes this: it is a change on the server.

3. Support for password authentication was removed

• (a) Authentication. A method the server no longer accepts is being sent.
• (b) The account password was typed instead of a token; or there is an old credential stored in the manager, holding the pre-migration password.
• (c) Generate a token with the necessary scope and, very importantly, delete the stored credential before retrying, or the manager will send the old one again:

4. REMOTE HOST IDENTIFICATION HAS CHANGED!

• (a) Authentication, but the other way round: it is the server that cannot prove its identity to you.
• (b) The server has been reinstalled or the platform has rotated its keys (the normal case); or somebody is intercepting the connection (the serious one).
• (c) Get the current fingerprint and compare it with the officially published one before touching anything:

Only if it matches the official one: ssh-keygen -R git.example.com and reconnect.

5. connect to host … port 22: Connection timed out

• (a) Neither of the two: this is a network problem. The connection never gets established, so there is no authentication and no authorisation.
• (b) A corporate firewall with port 22 closed (by far the most common), or the server is down.
• (c) Check connectivity and, if it is the firewall, change route:

Some platforms also offer SSH over port 443, which gets through those firewalls:

With this lesson the team can finally talk to the server. The essentials:

• Reading a public repository requires no credentials; writing always does, because push modifies the server's references.
• user.name and user.email authenticate nothing: they are commit metadata. Your access identity lives at another layer.
• Authentication (who you are) and authorisation (what you may do) are different. Permission denied (publickey) is the first; 403 Forbidden is the second. Telling them apart steers the diagnosis.
• HTTPS authenticates with a personal access token, which replaced the password because it is limited in scope, revocable, expirable, auditable and compatible with two-factor authentication. Always grant the minimum scope and use one token per machine.
• SSH authenticates with a key pair: the private key never leaves your disk, the public one is uploaded to the server. Generate with ssh-keygen -t ed25519 -C "description", set a passphrase, upload the .pub file, test with ssh -T and use ssh-agent so you only type it once.
• ~/.ssh/config solves the several-identities case, even two accounts on the same server, by means of invented aliases. IdentitiesOnly yes avoids Too many authentication failures.
• HTTPS versus SSH: HTTPS wins on corporate firewalls and permission granularity; SSH wins on day-to-day convenience, on never expiring and on handling several identities. Switching between them is a git remote set-url.
• Each system has its own credential manager: libsecret on Linux, osxkeychain on macOS and Git Credential Manager on Windows, which additionally opens the browser and manages the tokens for you: Carla's route.
• credential.helper store keeps the token in plain text in ~/.git-credentials. Avoid it on real machines; if there is no keyring, cache with a timeout is the better option.
• For everything else — commit signing, secret management, credentials leaked into the history — see lesson 08-05.

Ana, Bruno and Carla can now authenticate. The channel is open in both directions and, for the first time in the course, objects can travel from one .git/ to another.

In lesson 04-04: Fetching and Pulling Changes we start using it in the receiving direction, and we tackle Git's most widespread confusion head-on: the difference between git fetch and git pull. We will see why fetch never touches your working tree, what FETCH_HEAD is, how to inspect what has arrived before integrating it, and the various modes of git pull. And at last Carla clones task-manager and catches up with her colleagues' work.