Résolution des erreurs d'authentification Git courantes avec SSH et tokens
Corrigez les échecs d'authentification Git courants en faisant correspondre votre URL distante aux clés SSH, tokens HTTPS et aux gestionnaires d'identifiants.
Résolution des erreurs d'authentification Git courantes avec SSH et tokens
La plupart des problèmes d'authentification Git proviennent d'une inadéquation entre l'URL distante, l'identifiant que Git essaie d'utiliser et les permissions sur le compte d'hébergement Git. Le texte d'erreur peut sembler dramatique, mais la correction est généralement mécanique une fois que vous savez quel chemin Git emprunte.
Commencez par l'URL distante :
git remote -v
Si vous voyez https://github.com/org/repo.git, Git utilise HTTPS et aura besoin d'un nom d'utilisateur plus un token ou un gestionnaire d'identifiants capable d'en fournir un. Si vous voyez [email protected]:org/repo.git, Git utilise SSH et aura besoin d'une clé privée correspondant à une clé publique enregistrée auprès de l'hôte.
Ne mélangez pas les deux lors du dépannage. Choisissez HTTPS ou SSH, faites correspondre l'URL distante, puis testez ce chemin directement.
Lisez l'erreur littéralement
fatal: Authentication failed for 'https://...' signifie généralement que Git a atteint le serveur mais n'a pas présenté d'identifiant HTTPS valide. L'ancien identifiant peut être en cache, le token peut être expiré, ou le token peut ne pas avoir accès à ce dépôt.
remote: Permission to org/repo denied ou 403 Forbidden signifie généralement que votre identité a été reconnue mais n'a pas la permission pour l'opération. Par exemple, vous utilisez peut-être un token du mauvais compte, un token sans accès en écriture, ou une clé SSH attachée à un utilisateur différent.
Permission denied (publickey) signifie que SSH n'a pas proposé de clé que le serveur accepte.
Une invite répétée de nom d'utilisateur/mot de passe via HTTPS signifie généralement que Git reçoit un rejet et demande à nouveau. Saisir votre mot de passe de compte à plusieurs reprises n'aidera pas sur les hôtes qui exigent des tokens pour les opérations Git.
Correction de HTTPS avec un token d'accès personnel
Pour les dépôts distants HTTPS, créez un token d'accès personnel dans les paramètres de votre compte d'hébergement Git. Les noms de menus exacts diffèrent entre GitHub, GitLab, Bitbucket et les plateformes auto-hébergées, mais la forme est la même : créez un token, donnez-lui un accès au dépôt, définissez une expiration conforme à la politique de votre organisation, et copiez-le immédiatement.
Lorsque Git vous invite, utilisez votre nom d'utilisateur normal et collez le token comme mot de passe :
Username: your-username
Password: <paste-token-here>
Utilisez les permissions les plus restreintes qui fonctionnent. Pour un dépôt privé sur lequel vous poussez, vous avez besoin d'un accès en lecture et écriture au dépôt. Pour cloner des dépôts publics, vous n'avez peut-être pas besoin de token du tout. Les tokens granulaires et les règles SSO de l'organisation peuvent ajouter une autre couche : un token peut exister mais nécessiter encore une approbation ou une autorisation SSO avant de pouvoir accéder à un dépôt d'entreprise.
Si Git ne vous invite jamais à saisir le nouveau token, il utilise probablement un ancien identifiant en cache. Effacez l'entrée stockée pour l'hôte, puis réessayez.
Sur macOS, vérifiez dans le Trousseau d'accès les entrées liées à votre hôte Git, comme github.com ou git:https://github.com.
Sur Windows, ouvrez le Gestionnaire d'identifiants et supprimez l'identifiant générique pertinent pour l'hôte.
Sur Linux, inspectez votre helper configuré :
git config --global --get credential.helper
git config --show-origin --get-all credential.helper
Le helper cache stocke les identifiants temporairement en mémoire. Le helper store les écrit sur le disque en texte brut sauf si vous configurez une couche de stockage plus sécurisée, utilisez-le donc avec précaution. Le système de helper d'identifiants de Git est conçu pour demander des identifiants aux helpers et laisser les helpers sauvegarder ceux qui réussissent ; la sécurité dépend du helper que vous choisissez.
Une séquence de réinitialisation HTTPS utile est :
git remote -v
git config --show-origin --get-all credential.helper
# supprimez l'ancien identifiant du magasin d'identifiants du système d'exploitation
git ls-remote origin
git ls-remote origin est un test propre car il contacte le dépôt distant sans modifier votre arbre de travail.
Correction de SSH avec des clés
Pour les dépôts distants SSH, vérifiez d'abord si vous avez déjà des clés :
ls -al ~/.ssh
Les noms de clés courants incluent id_ed25519, id_rsa, et des noms spécifiques à l'hôte comme github_work_ed25519. Le fichier .pub est la clé publique que vous téléchargez sur l'hôte Git. Le fichier sans .pub est privé et ne doit pas être partagé.
Si vous avez besoin d'une nouvelle clé, Ed25519 est un bon choix par défaut sur les systèmes modernes :
ssh-keygen -t ed25519 -C "[email protected]"
Utilisez une phrase de passe sauf si votre environnement a une raison d'automatisation spécifique de ne pas le faire. Ajoutez ensuite la clé publique à votre compte d'hébergement Git ou aux paramètres de clé de déploiement :
cat ~/.ssh/id_ed25519.pub
Testez la connexion directement :
ssh -T [email protected]
Pour GitLab ou Bitbucket, remplacez le nom d'hôte. Un test réussi affiche généralement un message de bienvenue ou un message indiquant que l'accès shell n'est pas fourni. Ce n'est pas grave ; l'authentification Git-over-SSH peut toujours fonctionner.
Si SSH échoue toujours, demandez au client SSH ce qu'il fait :
ssh -vT [email protected]
Recherchez les lignes indiquant quelles clés sont proposées. Si votre clé n'est pas proposée, chargez-la dans l'agent :
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
Pour plusieurs comptes sur le même hôte, utilisez ~/.ssh/config pour que Git sache quelle clé appartient à quel dépôt distant :
Host github-work
HostName github.com
User git
IdentityFile ~/.ssh/github_work_ed25519
IdentitiesOnly yes
Puis pointez le dépôt vers cet alias :
git remote set-url origin git@github-work:org/repo.git
Cela évite le problème courant où SSH propose votre clé personnelle à un dépôt professionnel.
Changer de protocole proprement
Si votre équipe standardise sur SSH, changez un dépôt distant HTTPS comme ceci :
git remote set-url origin [email protected]:ORG/REPO.git
Si votre entreprise bloque SSH ou exige une inspection HTTPS, changez dans l'autre sens :
git remote set-url origin https://github.com/ORG/REPO.git
Après avoir changé l'URL, testez avec une opération de lecture :
git fetch origin
Puis testez l'action qui a échoué :
git push origin HEAD
Si fetch fonctionne mais que push échoue, l'authentification est probablement valide et l'autorisation est le problème. Vérifiez la protection de branche, le rôle de dépôt, la portée du token et les règles SSO de l'organisation.
Environnements CI et serveurs
Sur les agents de build et les serveurs, évitez d'utiliser un token personnel d'un humain lorsque c'est possible. Préférez les clés de déploiement, les utilisateurs machines ou le magasin d'identifiants intégré de votre système CI. Gardez les secrets hors de l'historique des commandes et des journaux. Ne collez pas de tokens dans les URL distantes comme ceci, sauf si vous êtes dans un environnement jetable contrôlé :
https://[email protected]/org/repo.git
Ce style peut fuiter via les journaux, les listes de processus, l'historique du shell et les fichiers de configuration.
Pour Jenkins, les runners GitHub Actions, les runners GitLab et les systèmes similaires, stockez les identifiants dans le mécanisme secret de la plateforme et injectez-les uniquement pour le travail qui en a besoin.
Une liste de vérification rapide
Exécutez-les dans l'ordre lorsque vous êtes bloqué :
git remote -v
git ls-remote origin
Si l'URL est HTTPS, effacez les anciens identifiants en cache et utilisez un token actuel avec les bonnes permissions de dépôt.
Si l'URL est SSH, exécutez :
ssh -T git@votre-nom-d-hote
ssh -vT git@votre-nom-d-hote
Confirmez que la clé attendue est proposée et que sa moitié publique est enregistrée avec le bon compte.
Si l'authentification réussit mais que push échoue, recherchez les règles d'autorisation : branches protégées, rôle d'écriture manquant, autorisation SSO expirée, clés de déploiement en lecture seule, ou tokens sans permission d'écriture.
La correction fiable n'est pas d'essayer des mots de passe aléatoires. Faites correspondre le protocole distant au type d'identifiant, supprimez les identifiants en cache obsolètes, testez la connexion directement, puis vérifiez les permissions sur le dépôt.