Corriger l’erreur Git « Permission denied (publickey) » en 3 minutes

L’erreur Git :

Permission denied (publickey).
fatal: Could not read from remote repository.

signifie presque toujours que le serveur Git (GitHub, GitLab, Bitbucket, ou un serveur SSH interne) a refusé votre authentification SSH. Autrement dit : Git essaie de se connecter en SSH, mais la clé publique attendue n’est pas présentée, n’est pas acceptée, ou vous n’utilisez pas la bonne identité.

Ce tutoriel vous donne une méthode rapide (diagnostic + correction) et en même temps approfondie pour comprendre exactement ce qui se passe, avec des commandes réelles. Objectif : rétablir un git pull / git push en quelques minutes.

1) Comprendre le message d’erreur (ce que SSH vous dit vraiment)

Quand vous utilisez une URL du type :

• git@github.com:org/repo.git
• git@gitlab.com:group/repo.git
• ssh://git@serveur-interne:2222/projets/repo.git

Git ne “parle” pas directement au serveur Git : il lance SSH, qui tente une authentification. L’erreur Permission denied (publickey) signifie :

• SSH a tenté une ou plusieurs clés (ou aucune),
• le serveur a répondu : aucune des clés proposées n’est autorisée pour ce compte (git, gitlab, etc.),
• donc la connexion est refusée.

Les causes les plus fréquentes :

1. Aucune clé SSH n’existe sur votre machine.
2. La clé existe mais n’est pas chargée dans l’agent SSH.
3. La clé est chargée mais la mauvaise clé est utilisée (multi-comptes, clés multiples).
4. La clé publique n’est pas ajoutée à votre compte Git (GitHub/GitLab…).
5. Vous utilisez la mauvaise URL distante (SSH vs HTTPS, mauvais hôte, mauvais utilisateur).
6. Problème de config SSH (~/.ssh/config) ou permissions de fichiers.
7. Sur macOS/Windows : interaction avec le trousseau/agent, ou clé stockée ailleurs.

2) Vérifier quelle URL distante vous utilisez (SSH ou HTTPS)

Avant de toucher aux clés, vérifiez comment votre dépôt est configuré :

git remote -v

Exemples :

• SSH (problème probable de clé) :

  origin  git@github.com:mon-org/mon-repo.git (fetch)
  origin  git@github.com:mon-org/mon-repo.git (push)

• HTTPS (l’erreur publickey ne devrait pas arriver ici) :

  origin  https://github.com/mon-org/mon-repo.git (fetch)
  origin  https://github.com/mon-org/mon-repo.git (push)

Si vous voyez une URL SSH (git@...), continuez.

Si vous vouliez utiliser HTTPS (par exemple en entreprise, ou si SSH est bloqué), vous pouvez basculer :

git remote set-url origin https://github.com/mon-org/mon-repo.git

Mais si vous souhaitez corriger SSH (souvent préférable), gardez l’URL SSH.

3) Diagnostic express : tester la connexion SSH au serveur Git

Testez la connexion SSH brute (sans Git) :

GitHub

ssh -T git@github.com

GitLab

ssh -T git@gitlab.com

Serveur interne

ssh -T git@mon-serveur

Résultats possibles :

• Succès (GitHub) :

  Hi mon-user! You've successfully authenticated, but GitHub does not provide shell access.

  Dans ce cas, SSH marche. Si Git échoue encore, c’est peut-être l’URL du dépôt, les droits du repo, ou un autre hôte.

• Échec :

  Permission denied (publickey).

  On continue.

4) Voir quelles clés SSH existent sur votre machine

Listez les clés courantes :

ls -la ~/.ssh

Vous cherchez typiquement :

• id_ed25519 (privée) et id_ed25519.pub (publique)
• ou id_rsa / id_rsa.pub (ancien, moins recommandé)
• éventuellement des clés nommées : id_ed25519_github, work_gitlab, etc.

Si le dossier ~/.ssh n’existe pas :

mkdir -p ~/.ssh
chmod 700 ~/.ssh

5) Créer une clé SSH (si vous n’en avez pas)

Recommandé : ED25519

ssh-keygen -t ed25519 -C "vous@exemple.com"

Quand il demande le chemin :

• Appuyez sur Entrée pour accepter ~/.ssh/id_ed25519, ou
• donnez un nom spécifique (utile si multi-comptes), ex. ~/.ssh/id_ed25519_github.

Quand il demande une passphrase :

• mettez-en une (recommandé), ou laissez vide (moins sûr).

Vérifiez que les fichiers existent :

ls -l ~/.ssh/id_ed25519 ~/.ssh/id_ed25519.pub

6) Démarrer l’agent SSH et y ajouter la clé

L’agent SSH garde vos clés en mémoire pour éviter de retaper la passphrase.

Linux / macOS (shell bash/zsh)

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

Si vous avez nommé la clé autrement :

ssh-add ~/.ssh/id_ed25519_github

Vérifiez les clés chargées :

ssh-add -l

Vous devriez voir une empreinte, par exemple :

256 SHA256:... ~/.ssh/id_ed25519 (ED25519)

Cas fréquent : “The agent has no identities.”

Cela signifie qu’aucune clé n’est chargée : refaites ssh-add ....

7) Ajouter la clé publique à GitHub/GitLab (étape indispensable)

Le serveur doit connaître votre clé publique.

Affichez la clé publique :

cat ~/.ssh/id_ed25519.pub

Copiez toute la ligne (commence par ssh-ed25519 et finit par votre commentaire).

GitHub

1. Allez dans Settings → SSH and GPG keys
2. New SSH key
3. Collez la clé publique
4. Sauvegardez

GitLab

1. Preferences → SSH Keys
2. Collez la clé publique
3. Ajoutez

Ensuite, retestez :

ssh -T git@github.com
# ou
ssh -T git@gitlab.com

8) Comprendre “mauvaise clé utilisée” (le piège n°1)

Vous pouvez avoir plusieurs clés :

• une clé perso pour GitHub
• une clé pro pour GitLab entreprise
• une clé ancienne id_rsa
• une clé générée par un outil

SSH choisit une clé selon :

• ce qui est chargé dans l’agent,
• les fichiers par défaut (id_ed25519, id_rsa, etc.),
• votre configuration ~/.ssh/config,
• et parfois l’ordre de tentative.

Voir quelle clé SSH est réellement tentée (commande essentielle)

Utilisez le mode verbeux :

ssh -vT git@github.com

Ou encore plus verbeux :

ssh -vvvT git@github.com

Cherchez des lignes comme :

• Offering public key: /Users/.../.ssh/id_ed25519
• Offering public key: ...
• puis Server accepts key: ... (bon signe)
• ou au contraire aucune acceptée → Permission denied (publickey).

Si vous voyez que SSH propose une clé qui n’est pas celle que vous avez ajoutée à GitHub/GitLab, il faut forcer l’identité.

9) Forcer la bonne clé via ~/.ssh/config (solution robuste)

Créez/éditez ~/.ssh/config :

nano ~/.ssh/config

Exemple pour GitHub avec une clé dédiée :

Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_github
  IdentitiesOnly yes

Pour GitLab :

Host gitlab.com
  HostName gitlab.com
  User git
  IdentityFile ~/.ssh/id_ed25519_gitlab
  IdentitiesOnly yes

Explications profondes :

• IdentityFile indique quelle clé privée utiliser.
• IdentitiesOnly yes dit à SSH : “n’essaie pas toutes les clés de l’agent, utilise uniquement celles déclarées ici”.
  C’est souvent ce qui résout les refus quand le serveur limite le nombre de tentatives ou quand vous avez trop de clés.

Assurez-vous que les permissions sont correctes :

chmod 600 ~/.ssh/config
chmod 600 ~/.ssh/id_ed25519_github
chmod 644 ~/.ssh/id_ed25519_github.pub
chmod 700 ~/.ssh

Rechargez la clé dans l’agent si besoin :

ssh-add ~/.ssh/id_ed25519_github

Puis testez :

ssh -T git@github.com

10) Cas multi-comptes GitHub : utiliser des hôtes alias

Si vous avez deux comptes GitHub (perso + pro), vous ne pouvez pas distinguer uniquement par github.com si vous devez utiliser deux clés différentes. La solution : un alias d’hôte.

Dans ~/.ssh/config :

Host github-perso
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_perso
  IdentitiesOnly yes

Host github-pro
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_pro
  IdentitiesOnly yes

Ensuite, changez l’URL du remote Git pour utiliser l’alias :

git remote set-url origin git@github-pro:org/repo.git

Test :

ssh -T git@github-pro

11) Vérifier les droits et l’existence du dépôt distant

Parfois l’auth SSH marche, mais vous n’avez pas accès au dépôt, ou l’URL est incorrecte.

Vérifier l’URL exacte

Sur GitHub, l’URL SSH ressemble à :

• git@github.com:OWNER/REPO.git

Sur GitLab :

• git@gitlab.com:GROUPE/REPO.git

Si vous avez un doute, comparez avec l’URL affichée sur la page du repo (bouton “Code” / “Clone”).

Tester avec git ls-remote

Cette commande teste l’accès sans cloner :

git ls-remote origin

Si ça échoue avec Permission denied (publickey), c’est bien SSH.
Si ça échoue avec “Repository not found” ou “access denied”, c’est plutôt un problème de droits/URL.

12) Problèmes de permissions de fichiers SSH (souvent sur Linux)

SSH refuse parfois d’utiliser des clés si les permissions sont trop ouvertes (par sécurité). Symptômes : SSH ignore votre clé, ou affiche des avertissements en mode -v.

Fix standard :

chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub
chmod 600 ~/.ssh/authorized_keys 2>/dev/null || true
chmod 600 ~/.ssh/config 2>/dev/null || true

13) Erreurs liées au port 22 bloqué (réseaux d’entreprise, Wi‑Fi publics)

Dans certains environnements, le port SSH 22 est filtré. Vous pouvez voir des timeouts ou des erreurs de connexion, mais parfois cela se mélange avec des échecs d’auth.

GitHub via port 443 (SSH)

GitHub propose ssh.github.com sur le port 443.

Dans ~/.ssh/config :

Host github.com
  HostName ssh.github.com
  Port 443
  User git
  IdentityFile ~/.ssh/id_ed25519_github
  IdentitiesOnly yes

Test :

ssh -T git@github.com

GitLab

GitLab.com supporte aussi des alternatives selon configuration, mais cela dépend. En entreprise, demandez l’hôte/port SSH exact.

14) Nettoyer une configuration confuse : méthode “reset contrôlé”

Si vous êtes perdu, voici une approche propre :

1. Sauvegardez votre dossier SSH :

   cp -a ~/.ssh ~/.ssh.backup.$(date +%Y%m%d%H%M%S)

2. Créez une nouvelle clé dédiée (ex. GitHub) :

   ssh-keygen -t ed25519 -C "github" -f ~/.ssh/id_ed25519_github

3. Ajoutez-la à l’agent :

   eval "$(ssh-agent -s)"
   ssh-add ~/.ssh/id_ed25519_github

4. Configurez ~/.ssh/config minimal :

   cat > ~/.ssh/config <<'EOF'
   Host github.com
     HostName github.com
     User git
     IdentityFile ~/.ssh/id_ed25519_github
     IdentitiesOnly yes
   EOF
   chmod 600 ~/.ssh/config

5. Ajoutez la clé publique à GitHub :

   cat ~/.ssh/id_ed25519_github.pub

6. Testez :

   ssh -T git@github.com

7. Retestez Git :

   git fetch
   git pull
   git push

15) Vérifier que Git utilise bien SSH (et pas un wrapper)

Parfois, des variables d’environnement ou outils (VS Code, GUI Git, etc.) modifient la commande SSH.

Voir la commande SSH utilisée par Git

Git utilise ssh par défaut, mais peut être configuré :

git config --global core.sshCommand
git config --local core.sshCommand

Si vous voyez une valeur, elle peut forcer une clé ou un binaire différent. Exemple utile :

git config --global core.sshCommand "ssh -i ~/.ssh/id_ed25519_github -o IdentitiesOnly=yes"

Vous pouvez aussi la supprimer pour revenir au défaut :

git config --global --unset core.sshCommand

16) Débogage “ultime” : reproduire exactement ce que Git fait

Vous pouvez demander à Git de tracer la connexion SSH :

GIT_SSH_COMMAND="ssh -vvv" git fetch

Ou forcer une clé :

GIT_SSH_COMMAND="ssh -i ~/.ssh/id_ed25519_github -o IdentitiesOnly=yes -vvv" git fetch

Ce mode est extrêmement informatif : vous verrez quelles clés sont proposées et pourquoi elles sont refusées.

17) Checklist “3 minutes” (résumé actionnable)

Si vous voulez aller vite, suivez cette liste dans l’ordre :

1. Vérifier le remote :

   git remote -v

2. Tester SSH :

   ssh -T git@github.com

3. Vérifier clés existantes :

   ls -la ~/.ssh

4. Si pas de clé, en créer une :

   ssh-keygen -t ed25519 -C "vous@exemple.com"

5. Démarrer l’agent + ajouter la clé :

   eval "$(ssh-agent -s)"
   ssh-add ~/.ssh/id_ed25519
   ssh-add -l

6. Ajouter la clé publique au site (GitHub/GitLab) :

   cat ~/.ssh/id_ed25519.pub

7. Si toujours KO, voir quelle clé est proposée :

   ssh -vvvT git@github.com

8. Forcer la bonne clé via ~/.ssh/config :

   Host github.com
     User git
     IdentityFile ~/.ssh/id_ed25519
     IdentitiesOnly yes

9. Retester :

   ssh -T git@github.com
   git fetch

18) Erreurs voisines et ce qu’elles signifient

• Permission denied (publickey,password).
  Le serveur autorise plusieurs méthodes, mais aucune n’a réussi. Souvent clé non ajoutée, ou mauvais utilisateur.

• Repository not found.
  Auth OK, mais repo inexistant ou vous n’avez pas les droits.

• Host key verification failed.
  Problème de clé d’hôte (known_hosts). Ce n’est pas la même chose que publickey. Il faut vérifier ~/.ssh/known_hosts.

• Too many authentication failures
  Trop de clés tentées. Solution typique : IdentitiesOnly yes + IdentityFile dans ~/.ssh/config.

Conclusion

Permission denied (publickey) n’est pas une “erreur Git” au sens strict : c’est SSH qui vous dit que l’identité présentée ne correspond à aucune clé autorisée sur le serveur. La résolution fiable consiste à :

1. Avoir une clé (idéalement ED25519),
2. La charger dans l’agent,
3. Ajouter la clé publique au service Git,
4. Forcer la bonne clé via ~/.ssh/config si vous avez plusieurs identités,
5. Tester avec ssh -T et ssh -vvvT pour comprendre exactement ce qui est tenté.

Si vous me donnez la sortie (anonymisée) de :

git remote -v
ssh -vvvT git@github.com
ls -la ~/.ssh
ssh-add -l

je peux vous indiquer précisément quelle étape bloque et quelle ligne corriger.