SHA256 repositories in Forgejo Actions

Le sujet va intéresser au moins autant de gens que la migration des adresses IPv4 vers IPv6, mais je vais tout de même vous parler de l'utilisation de l'algorithme de hachage SHA256 dans Git.

La visée de cet article est simple : débloquer les quelques personnes avant-gardistes qui auraient eu l'idée de créer des repositories en SHA256 et qui se retrouveraient bloquées au moment du checkout dans la CI Actions. Pour ces avant-gardistes doublées d'une pointe d'impatience, rendez-vous directement à la fin de l'article : la solution tient en une simple variable d'environnement.

Pour les autres, et pour moi-même, cultivons-nous ensemble en repassant l'historique de ce changement.

Fonctionnement de Git

Git identifie tous les objets d'un repository par des empreintes de hachage. Un fichier, un répertoire, mais aussi un commit ou une branche : tout est représenté par une empreinte.

À l'origine, Linus Torvalds a choisi SHA1 comme algorithme de hachage en 2005. Concrètement, une empreinte SHA1 ressemble à ça : a94a8fe5ccb19ba61c4c0873d391e987982fbbd3. Quarante caractères hexadécimaux dont l'objectif est d'identifier de manière unique n'importe quel objet.

Nécessité d'un changement

En 2017, des équipes chez Google ont fait la démonstration qu'il était possible de forcer une collision sur une empreinte.

Cette attaque a un nom : SHAttered. Elle a nécessité une puissance de calcul colossale, mais elle a suffi à sonner le glas de SHA1.

Quand on ne baigne pas dedans, on ne se rend pas compte des conséquences. Cela veut dire qu'une personne malveillante peut remplacer un fichier par un autre tout en préservant la validation de son empreinte. Les acteurs malveillants peuvent alors substituer une mise à jour logicielle par une autre sans que la vérification de son empreinte ne bronche. Ou encore remplacer un contrat signé électroniquement par un autre.

Bref, n'utilisez plus jamais SHA1 dans vos logiciels.

Et pour Git alors ?

Dès 2017, Git embarque sha1collisiondetection, qui détecte les tentatives de collision de type SHAttered.

Ce n'est qu'un pansement, mais il a permis à la communauté Git de prendre le temps de trouver un remplaçant à SHA1. C'est finalement SHA256 qui a été choisi qui a été retenu.

En 2020, avec sa version 2.29, la commande git permet de créer un repository en SHA256.

Après plusieurs itérations d'amélioration, c'est concomitamment avec la version 2.51 en août 2025 que les mainteneurs décident de marquer SHA256 comme algorithme par défaut pour la future version 3.0.

Du côté des plate-formes, GitLab et Forgejo apportent le support en 2024.

Le bloquant dans l'adoption de SHA256, c'est GitHub, qui n'apporte toujours pas de support.

Forgejo Actions

J'en viens à mon cas personnel. J'utilise Forgejo comme plate-forme auto-hébergée. Si vous ne connaissez pas, c'est une forge logicielle qui s'inspire très largement de GitHub et utilise les Actions comme CI. De fait, ce sont donc des modules GitHub qui sont réutilisés.

Comme on l'a vu, GitHub n'apporte pas le meilleur support de SHA256. Voici la discussion qui en demande le support depuis un bon moment maintenant, pour le module checkout. Celui-là même qui permet de récupérer le code qui va être buildé.

Si au moins le message d'erreur était clair… Pour ma part, voici le genre de message que j'obtenais :

[command]/usr/bin/git -c protocol.version=2 fetch --no-tags --prune --no-recurse-submodules --depth=1 origin +a310bb1e98ee34254decb508aba673ac508123a42e479cb35002fe3a7fc17c9c:refs/remotes/origin/main
fatal: couldn't find remote ref a310bb1e98ee34254decb508aba673ac508123a42e479cb35002fe3a7fc17c9c

Heureusement, le support n'est pas totalement inexistant, et il suffit de l'activer par une variable d'environnement. Voici donc ce que j'ai ajouté dans mon workflow Forgejo et qui a tout débloqué :

env:
  GIT_DEFAULT_HASH: sha256

Petit avertissement au passage : cette solution repose sur une variable d'environnement non documentée officiellement côté checkout. Ça fonctionne aujourd'hui, mais gardez un œil sur l'issue, car une prise en charge native pourrait tout changer.

Faut-il migrer ?

Franchement, à moins d'être un curieux qui veut prendre de l'avance sur un repository pas trop compliqué, je ne le recommande pas. L'éco-système n'est pas encore mûre sur le sujet. Les défis sont encore importants : que se passe-t-il si j'utilise un sous module SHA1 dans un repository SHA256 ? Les développeurs de Git travaillent encore sur un mode de traduction entre les deux méthodes de hachage.