Signer les commits Git avec GPG et SSH

Signer un commit y attache une signature cryptographique qui prouve qui l'a créé et que son contenu n'a pas été modifié. Ce chapitre explique pourquoi les signatures sont importantes, comment générer une clé, comment signer des commits et des tags avec GPG ou SSH, comment vérifier les signatures, et comment corriger les erreurs que vous rencontrerez probablement la première fois.

Ce que prouve réellement une signature

Par défaut, le nom d'auteur et l'e-mail d'un commit ne sont que du texte. Git ne les vérifie jamais — n'importe qui peut définir user.name et user.email avec n'importe quelle valeur (voir git config) et produire un commit qui prétend provenir de quelqu'un d'autre. Une signature change cela : elle est créée avec une clé privée que vous seul détenez, et toute personne possédant votre clé publique correspondante peut confirmer deux choses :

Paternité — le commit provient réellement du détenteur de cette clé privée.
Intégrité — si un seul octet du commit (message, arborescence, parent, auteur) change, la vérification échoue.

Pour les projets où la provenance est importante — code sensible à la sécurité, publications open-source, environnements réglementés — un historique signé permet aux réviseurs de savoir avec certitude qui a écrit quoi. Sur GitHub et GitLab, une signature vérifiée donne droit à un badge vert Verified à côté du commit.

Note

Une signature ne chiffre rien. Le commit et son contenu restent entièrement lisibles ; la signature atteste uniquement l'origine et l'intégrité.

Choisir entre GPG et SSH

Git prend en charge deux formats de signature. Choisissez-en un :

GPG (OpenPGP) — le choix traditionnel. Mature, largement pris en charge, mais la gestion des clés (trousseaux, expiration, l'agent gpg) nécessite une courbe d'apprentissage.
SSH — disponible depuis Git 2.34. Si vous utilisez déjà une clé SSH pour pousser des changements, vous pouvez la réutiliser pour signer avec presque aucune configuration supplémentaire. Plus simple à gérer, c'est désormais le point de départ recommandé pour la plupart des gens.

Vérifiez d'abord votre version :

git --version

Signer avec GPG

Générer ou trouver une clé

Si vous n'avez pas encore de clé GPG, créez-en une (acceptez les valeurs par défaut, en choisissant une clé RSA 4096 bits ou une clé ECC) :

gpg --full-generate-key

Listez vos clés et copiez l'ID de clé long — la valeur après l'algorithme sur la ligne sec :

gpg --list-secret-keys --keyid-format=long

sec   ed25519/3AA5C34371567BD2 2024-01-08 [SC]
      AB1C2D3E...
uid   Jane Dev <[email protected]>

Ici l'ID de clé est 3AA5C34371567BD2.

Configurer Git

git config --global user.signingkey 3AA5C34371567BD2
git config --global commit.gpgsign true

Signer un commit ou un tag

Avec commit.gpgsign activé, chaque commit est signé automatiquement. Pour signer un seul commit explicitement, utilisez le drapeau -S en majuscule :

git commit -S -m "Add audited payment handler"

Pour signer un tag annoté, utilisez le -s en minuscule :

git tag -s v2.0.0 -m "Signed release 2.0.0"

Avertissement

La casse est importante : -S (majuscule) signe un commit, tandis que -s (minuscule) signe un tag. Avec git commit, le -s minuscule ajoute à la place une ligne Signed-off-by — un certificat d'origine textuel du développeur, pas une signature cryptographique.

Signer avec SSH

Si vous avez une clé id_ed25519 (ou toute autre clé SSH), indiquez à Git la clé publique et changez le format de signature :

git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519.pub
git config --global commit.gpgsign true

Les commits et les tags se signent maintenant avec les mêmes drapeaux -S / -s qu'avant — aucune autre modification n'est nécessaire.

Activer la vérification locale pour SSH

Contrairement à GPG, Git ne dispose pas de magasin de confiance intégré pour les clés SSH, donc git log --show-signature indique No principal matched jusqu'à ce que vous créiez un fichier de signataires autorisés. Associez chaque adresse e-mail à sa clé publique :

mkdir -p ~/.config/git
echo "[email protected] $(cat ~/.ssh/id_ed25519.pub)" >> ~/.config/git/allowed_signers
git config --global gpg.ssh.allowedSignersFile ~/.config/git/allowed_signers

Téléverser votre clé publique vers l'hébergeur

Le badge Verified n'apparaît qu'après que l'hébergeur dispose de votre clé publique.

GPG : copiez la clé publique blindée depuis gpg --armor --export <key-id> et collez-la sous Paramètres → Clés SSH et GPG → Nouvelle clé GPG.
SSH : ajoutez le contenu de ~/.ssh/id_ed25519.pub en tant que clé de type Clé de signature (distincte d'une clé d'authentification) dans la même zone de paramètres.

L'adresse e-mail de votre clé doit correspondre à l'e-mail d'auteur du commit, sinon l'hébergeur affiche Unverified.

Vérifier les signatures

Vérifiez les signatures localement avec l'une de ces commandes :

git log --show-signature          # show signature status in the log
git verify-commit HEAD            # verify one commit
git verify-tag v2.0.0             # verify a tag

Pour une vue compacte, le paramètre fictif %G? dans git log affiche un code d'état par commit :

git log --pretty="%h %G? %s"

a1b2c3d G  Add audited payment handler
d4e5f6g N  Quick typo fix

G signifie une bonne signature (valide), B mauvaise, U bonne avec validité inconnue, et N aucune signature.

Erreurs courantes et corrections

error: gpg failed to sign the data — l'agent GPG ne peut généralement pas demander votre phrase de passe. Exportez le terminal qu'il doit utiliser : export GPG_TTY=$(tty) (ajoutez-le à ~/.bashrc ou ~/.zshrc). Sur macOS, installez pinentry-mac pour que l'agent puisse afficher une boîte de dialogue de mot de passe.
gpg: signing failed: No secret key — user.signingkey pointe vers le mauvais ID. Vérifiez à nouveau avec gpg --list-secret-keys --keyid-format=long.
GitHub affiche Unverified — l'e-mail d'auteur du commit ne correspond pas à un e-mail associé à votre clé téléversée, ou la clé n'a pas été ajoutée à l'hébergeur.
No principal matched (SSH) — vous n'avez pas configuré gpg.ssh.allowedSignersFile (voir ci-dessus).

Options courantes

Commande	Description
`git commit -S`	Signe un seul commit.
`git tag -s <name>`	Crée un tag annoté signé.
`git config commit.gpgsign true`	Signe chaque commit automatiquement.
`git config gpg.format ssh`	Signe avec une clé SSH plutôt qu'avec GPG.
`git log --show-signature`	Affiche l'état de la signature dans le journal.
`git log --pretty="%G?"`	Affiche un code d'état de signature par commit.
`git verify-commit <commit>`	Vérifie la signature d'un commit.
`git verify-tag <tag>`	Vérifie la signature d'un tag.

Pratique

Quelles affirmations sur la signature des commits sont correctes ?

Une signature prouve la paternité et garantit que le contenu du commit n'a pas été modifié.Sans signature, le nom d'auteur et l'e-mail d'un commit peuvent être définis sur n'importe quelle valeur.Git peut signer des commits avec une clé GPG ou, dans les versions modernes, une clé SSH.'commit.gpgsign true' signe chaque commit automatiquement.Une signature est impossible à vérifier localement et ne fonctionne que sur les plateformes d'hébergement.