Clé SSH GitHub/GitLab qui ne marche pas ? Le correctif pas à pas

Une clé SSH qui refuse de s’authentifier auprès de GitHub ou GitLab est l’un des problèmes de développeur les plus googlés qui soient, et la moitié du temps la clé va très bien — c’est le diagnostic qui est faux. Alors avant de régénérer quoi que ce soit, lancez un test et apprenez à en lire la réponse. Puis traitez les coupables dans l’ordre de leur fréquence réelle.

« You’ve successfully authenticated, but GitHub does not provide shell access »

Si c’est la ligne que vous avez reçue en retour, arrêtez — votre clé fonctionne déjà. GitHub et GitLab ne vous donnent pas de shell ; ils ne parlent que git par-dessus SSH, donc ils vous authentifient et raccrochent aussitôt, et « does not provide shell access » est leur façon de le dire, pas une erreur. La formulation de GitLab est un peu différente (Welcome to GitLab, @you!) mais veut dire la même chose. Si votre clé fonctionne et que git push réclame quand même un mot de passe, la clé n’a jamais été le problème — passez au coupable du remote HTTPS ci-dessous, qui est la vraie cause habituelle.

Étape 0 : le test qui vous dit si c’est réellement cassé

Demandez directement à l’hôte git s’il reconnaît votre clé :

ssh -T git@github.com        # GitHub
ssh -T git@gitlab.com        # GitLab

Maintenant, lisez la réponse attentivement, car le message de succès ressemble à une erreur :

Hi <username>! You've successfully authenticated, but GitHub does not
provide shell access.

C’est un succès. « Does not provide shell access » n’est pas un échec — GitHub et GitLab ne vous donnent pas de shell, ils ne parlent que git par-dessus SSH, donc ils vous authentifient puis raccrochent. Les gens voient « does not provide » et se mettent à dépanner une configuration qui marche. Si vous voyez votre nom d’utilisateur sur cette ligne, votre clé fonctionne ; votre problème est ailleurs (passez au coupable du remote HTTPS ci-dessous — c’est le vrai souci habituel).

Le véritable échec ressemble plutôt à ceci :

git@github.com: Permission denied (publickey).

C’est celui-là que nous sommes là pour corriger. Notez l’endpoint : Permission denied (publickey) signifie que le serveur n’a accepté aucune clé que vous avez proposée. Descendez la liste.

Coupable 1 : la clé n’est pas ajoutée à votre compte

La vraie cause la plus fréquente. Une clé sur votre portable ne fait rien tant que sa moitié publique n’a pas été ajoutée à l’hôte git. Copiez la clé publique :

cat ~/.ssh/id_ed25519.pub     # note the .pub — this is the safe half to share

Collez-la dans GitHub → Settings → SSH and GPG keys → New SSH key, ou GitLab → Preferences → SSH Keys.

Une règle, sans exception : collez le fichier .pub, jamais le fichier sans .pub. La clé publique est une seule ligne qui commence par ssh-ed25519 AAAA… (ou ssh-rsa AAAA…). Si ce que vous êtes sur le point de coller commence par -----BEGIN OPENSSH PRIVATE KEY-----, arrêtez — c’est votre clé privée, le secret qui est votre identité. La coller dans un formulaire web livre votre identifiant à quiconque peut lire cette page. Partagez la moitié publique ; gardez la moitié privée.

(Pas encore de clé ? Générez-en une — Ed25519 dans presque tous les cas (en anglais) : ssh-keygen -t ed25519 -C "you@device".)

Coupable 2 : ce n’est pas la bonne clé qui est proposée

Votre clé est bien en place, mais SSH en propose une autre — fréquent quand vous avez plusieurs clés et que l’agent les essaie dans un ordre que le serveur rejette. Voyez exactement quelle clé est envoyée :

ssh -vT git@github.com

Cherchez les lignes Offering public key:. Si la clé que vous avez ajoutée n’y figure pas, ou si une mauvaise est acceptée, épinglez la bonne clé par hôte dans ~/.ssh/config :

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

IdentitiesOnly yes est la ligne clé — elle dit à SSH de ne proposer que le IdentityFile que vous avez nommé et d’arrêter d’arroser le serveur avec toutes les clés de votre agent (ce qui guérit aussi Too many authentication failures). Faites de même avec Host gitlab.com pour GitLab. Plus de détails sur la structuration du fichier dans le guide ssh_config (en anglais).

Coupable 3 : l’agent ne tourne pas, ou la clé n’est pas chargée

Si votre clé a une phrase secrète et que l’agent ne la détient pas, SSH peut l’ignorer en silence. Vérifiez ce que l’agent détient :

ssh-add -l

The agent has no identities (ou Could not open a connection to your authentication agent) signifie que vous devez le démarrer et charger la clé :

eval "$(ssh-agent -s)"        # start the agent in this shell
ssh-add ~/.ssh/id_ed25519     # load the key (prompts for the passphrase once)

ssh-add -l devrait maintenant lister l’empreinte de votre clé. (Pour ce que l’agent est réellement et comment il garde les clés, voyez qu’est-ce que l’agent SSH (en anglais).)

Coupable 4 : vous êtes sur un remote HTTPS, pas SSH

C’est le coupable derrière « ma clé fonctionne (ssh -T a réussi) mais git push réclame quand même un mot de passe ». Votre dépôt est configuré pour utiliser HTTPS, qui ignore totalement les clés SSH et veut un jeton. Vérifiez :

git remote -v

Si vous voyez https://github.com/you/repo.git, c’est le problème — HTTPS ne touche jamais à votre clé SSH. Basculez le remote vers SSH :

git remote set-url origin git@github.com:you/repo.git      # GitHub
git remote set-url origin git@gitlab.com:you/repo.git      # GitLab

Relancez git remote -v pour confirmer qu’il commence maintenant par git@. Ce seul correctif résout une énorme part des signalements « clé SSH qui ne marche pas » où la clé allait très bien depuis le début.

Coupable 5 : les permissions de ~/.ssh

SSH refuse d’utiliser des clés et une config que d’autres pourraient altérer. Si la sortie verbeuse mentionne de mauvais modes, ou si des clés sont ignorées sans raison claire :

chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519          # private key
chmod 644 ~/.ssh/id_ed25519.pub      # public key
chmod 600 ~/.ssh/config

Sous Windows, cela surgit après avoir copié des clés depuis un disque synchronisé ou entre machines ; corrigez via les propriétés de Sécurité du fichier, ou gardez vos clés hors des dossiers synchronisés dans le cloud.

Coupable 6 : on vous demande la phrase secrète à chaque fois

Si chaque opération git exige la phrase secrète de votre clé, c’est que l’agent ne la met pas en cache. Chargez-la une fois avec ssh-add (en anglais) (coupable 3), et faites-la tenir d’une session à l’autre en ajoutant à ~/.ssh/config :

Host github.com gitlab.com
    AddKeysToAgent yes

Sous macOS, ssh-add --apple-use-keychain ~/.ssh/id_ed25519 stocke la phrase secrète dans le Trousseau pour qu’elle survive aux redémarrages.

Coupable 7 : deux comptes, un seul hôte

Les comptes GitHub professionnel et personnel ne peuvent pas partager une seule clé — une clé publique donnée appartient à un seul compte. Donnez à chacun sa propre clé et un alias Host qui le sélectionne :

Host github-work
    HostName github.com
    User git
    IdentityFile ~/.ssh/work_ed25519
    IdentitiesOnly yes

Host github-personal
    HostName github.com
    User git
    IdentityFile ~/.ssh/personal_ed25519
    IdentitiesOnly yes

Ensuite, clonez ou définissez le remote avec l’alias comme hôte : git@github-work:org/repo.git. SSH fait correspondre github-work, choisit la clé professionnelle, et réécrit la connexion vers github.com en coulisses.

Coupable 8 : SSO d’organisation non autorisé (GitHub)

Vous vous authentifiez sans souci sur vos propres dépôts, mais vous obtenez Permission denied sur les dépôts d’une organisation derrière un SSO SAML. La clé existe mais n’est pas autorisée pour cette organisation. Allez dans Settings → SSH and GPG keys, trouvez la clé, cliquez sur Configure SSO, et autorisez-la pour l’organisation. GitLab a un cas parallèle où une clé expirée est rejetée en silence — vérifiez la date d’expiration de la clé dans SSH Keys si une clé qui marchait s’arrête soudain.

Quand c’est toujours Permission denied (publickey)

Si vous avez parcouru la liste et que vous butez toujours sur l’endpoint, vous avez réduit le problème à une vraie question d’acceptation de clé — la boucle méthodique pour cette erreur précise (lire ssh -vvv, la liste des méthodes du serveur, clés proposées vs acceptées) se trouve dans permission denied (publickey), un correctif rapide et méthodique (en anglais), et la carte plus large des erreurs SSH est dans les erreurs SSH décodées. Mais pour les hôtes git précisément, l’ordre ci-dessus attrape presque tout : ajoutez la clé publique, proposez la bonne, chargez-la dans l’agent, et assurez-vous d’être bien sur un remote SSH.

Là où un client supprime complètement la configuration

Une grande partie de ce frottement n’est que de la paperasse — quelle clé appartient à quel hôte, si elle est chargée, si le remote est bien en SSH. Termalin garde la clé avec l’hôte auquel elle appartient, déverrouille vos clés une fois via un agent intégré pour ne pas retaper les phrases secrètes (et une invite annulée ne saute jamais une clé en silence), et — parce qu’il parle le protocole ssh-agent standard — git et votre CLI peuvent signer à travers ce même agent. Les empreintes sont visibles par clé, si bien qu’ajouter la bonne moitié publique à GitHub ou GitLab est un copier-coller plutôt qu’une chasse à travers cinq dossiers ~/.ssh. La jonglerie comptes-et-alias ci-dessus devient un réglage par hôte au lieu d’un casse-tête de fichier de config.

---

Termalin est un client SSH gratuit et multiplateforme qui gère vos clés avec un agent à déverrouillage unique à travers lequel git peut signer — téléchargez-le, ou lisez comment il gère vos clés en toute sécurité.