Comment ajouter une clé SSH à GitHub

Générer une clé

Passez cette étape si vous en avez déjà une, ce que vous pouvez voir avec ls ~/.ssh/*.pub.

ssh-keygen -t ed25519 -C "you@example.com"

Acceptez le fichier par défaut et définissez une phrase secrète. Sous Windows, voir générer une clé sous Windows.

Vous hésitez sur le type ? Voir clés SSH RSA ou ed25519.

Copier la clé publique

pbcopy < ~/.ssh/id_ed25519.pub     # macOS
cat ~/.ssh/id_ed25519.pub          # Linux: copy the output by hand

Sous Windows, utilisez Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub | Set-Clipboard. C'est une seule ligne commençant par ssh-ed25519. Si ce que vous avez commence par -----BEGIN, il s'agit de la clé privée : arrêtez-vous et ne la collez nulle part.

L'ajouter sur GitHub

1. Cliquez sur votre photo de profil en haut à droite, puis sur Settings.
2. Dans la section Access de la barre latérale, cliquez sur SSH and GPG keys.
3. Cliquez sur New SSH key.
4. Donnez-lui un titre qui nomme la machine, comme « Personal laptop ».
5. Choisissez le type de clé Authentication. Signing est un autre usage : pour signer des commits avec la même clé, envoyez-la une seconde fois comme Signing.
6. Collez la clé sans ajouter de retours à la ligne, puis cliquez sur Add SSH key.

Avec l'outil en ligne de commande de GitHub, après gh auth login :

gh ssh-key add ~/.ssh/id_ed25519.pub --title "Personal laptop"

GitHub n'accepte plus les clés DSA. Si une organisation à laquelle vous appartenez utilise l'authentification unique SAML, il se peut aussi que vous deviez y autoriser la clé sur la même page.

La tester et vérifier l'empreinte

ssh -T git@github.com

La première fois, ssh demande s'il faut faire confiance à l'hôte. Comparez ce qu'il affiche avec la liste que publie GitHub. Nous avons vérifié que ces valeurs correspondent à ce qu'envoie github.com :

GitHub peut les changer : sa propre page fait donc référence. Une connexion réussie affiche :

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

Si vous obtenez une erreur à la place, voir git@github.com: Permission denied (publickey).

Pourquoi ssh demande la première fois, et comment lire la question : known_hosts et empreintes d'hôte expliqués.

Faire utiliser SSH à votre dépôt

Une clé ne sert à rien pour un dépôt cloné en HTTPS. Vérifiez, et changez si nécessaire :

git remote -v
git remote set-url origin git@github.com:OWNER/REPO.git

Pour un nouveau clone, utilisez la même forme d'adresse :

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

Si Git demande la phrase secrète ou prend la mauvaise clé

Chargez la clé dans ssh-agent une fois par session avec ssh-add ~/.ssh/id_ed25519. Sur Mac, le Trousseau peut garder la phrase secrète après un redémarrage : voir ssh-agent et le Trousseau macOS.

Si votre clé porte un autre nom, indiquez à ssh laquelle utiliser pour GitHub dans ~/.ssh/config :

Host github.com
    IdentityFile ~/.ssh/id_ed25519_github
    IdentitiesOnly yes

Pour un second compte GitHub sur la même machine, voir plusieurs comptes GitHub avec SSH.

Si le port 22 est bloqué

Certains réseaux le bloquent, ce qui se traduit par un délai dépassé. GitHub accepte aussi SSH sur le port 443 :

ssh -T -p 443 git@ssh.github.com

Si cela fonctionne, rendez-le permanent dans ~/.ssh/config :

Host github.com
    Hostname ssh.github.com
    Port 443
    User git

Questions

Pourquoi ssh -T git@github.com se termine-t-il avec un code d'erreur ?

Il se termine avec le code 1 même en cas de réussite, car GitHub ne fournit pas de shell. Ce qui compte, c'est le message Hi USERNAME.

Puis-je utiliser la même clé sur deux comptes GitHub ?

Non. GitHub identifie votre compte à partir de la clé et refuse une clé déjà utilisée avec Key already in use. Voir le guide sur les comptes GitHub multiples.

Pourquoi Git demande-t-il ma phrase secrète SSH à chaque push ?

Parce que la clé n'est pas chargée dans ssh-agent. Lancez ssh-add ~/.ssh/id_ed25519 une fois par session. Sur Mac, ssh-add --apple-use-keychain enregistre aussi la phrase secrète dans le Trousseau.

Sources

• Ajouter une nouvelle clé SSH à votre compte GitHub, GitHub Docs
• Tester votre connexion SSH, GitHub Docs
• Empreintes des clés SSH de GitHub, GitHub Docs
• Utiliser SSH sur le port HTTPS, GitHub Docs

Guides associés

• Comment générer une clé SSH ed25519
• "git@github.com: Permission denied (publickey)" : comment le corriger
• Comment utiliser plusieurs comptes GitHub avec SSH
• Comment générer une clé SSH sous Windows

Autres guides : Clés et connexion

• Le fichier authorized_keys expliqué
• Convertir une clé .ppk en OpenSSH, et inversement
• Comment désactiver la connexion par mot de passe pour SSH
• Comment utiliser une YubiKey ou une clé FIDO2 avec SSH (ed25519-sk)
• Comment corriger "Permission denied (publickey)" avec SSH
• Comment retrouver une clé publique SSH à partir de la clé privée

Tous les guides