Migrer des dépôts dont l’historique contient des secrets

fremforge exécute un hook de pré-réception gitleaks sur chaque push, y compris le push miroir initial qui amène l’historique d’un client dans une organisation fremforge. Si le dépôt source contient des secrets dans un commit historique (un ancien .env, une clé d’API divulguée, une clé SSL privée, etc.), le push d’import échoue et la migration est bloquée.

Cette page décrit les deux options prises en charge. L’option A est la voie recommandée pour la plupart des équipes ; l’option B est un dernier recours.

Option A : renouveler le secret et réécrire l’historique (recommandée)

À privilégier lorsque :

• Le secret divulgué est réel (clé d’API, clé privée SSH, certificat, mot de passe). Il doit être invalidé quel que soit l’hébergement du dépôt : le laisser dans l’historique git d’un hôte quelconque constitue une exposition permanente.
• L’équipe peut consacrer environ 1 heure à la réécriture de l’historique et au force-push vers la source.

Procédure :

1. Renouvelez d’abord le secret divulgué. Avant de toucher à git : changez la clé d’API, révoquez la clé SSH, renouvelez le certificat. La valeur divulguée doit être invalide avant la réécriture de l’historique ; ainsi, même si la réécriture est incomplète, la valeur est inoffensive.
2. Identifiez le ou les commits. La sortie gitleaks de la tentative d’import fremforge indique la règle et le SHA du commit. Assurez-vous de comprendre de quel secret et de quels commits il s’agit.
3. Réécrivez l’historique avec git filter-repo. (documentation en amont)

   # Install: brew install git-filter-repo  (or pip install git-filter-repo)
   # Verify upstream is clean:
   git clone --mirror <source-url> repo.git
   cd repo.git
   # Replace the secret value across history (string-replace shape):
   echo 'literal:AKIAEXAMPLE12345===>REDACTED' > replace.txt
   git filter-repo --replace-text replace.txt
   # OR: drop the file containing the secret across history:
   git filter-repo --invert-paths --path path/to/leaky/file
4. Force-pushez d’abord l’historique réécrit vers le dépôt source.
   • C’est la réécriture côté source qui rend la correction durable. Si vous ne poussez l’historique réécrit que vers fremforge, un attaquant qui a cloné la source avant la réécriture détient toujours la valeur divulguée.
   • GitHub : git push --force-with-lease --mirror
   • GitLab + ADO : idem. Les deux refusent par défaut le force-push vers les branches protégées ; assouplissez temporairement la protection, poussez, puis rétablissez-la.
5. Lancez la migration selon la procédure standard, voir github / gitlab / azure-devops.
6. Vérifiez après l’import que le journal gitleaks de fremforge n’indique aucun blocage pour le push de migration.

Mises en garde :

• Les forks et les clones conservent l’historique d’origine. Il est impossible de récupérer tous les clones : c’est pourquoi l’étape 1 (renouveler d’abord le secret) est l’étape déterminante.
• Réécrire l’historique casse toutes les PR/MR et branches ouvertes sur la source. Coordonnez-vous avec l’équipe avant de valider ; certains hôtes retirent proprement les PR lors d’un rebase, d’autres les présentent comme « fusionnées en N+1 commits ».
• L’intégrité des tags et des signatures est rompue : tout tag signé pointant vers un commit réécrit n’est plus valide. Recréez les tags après la réécriture.

Option B : partir d’un dépôt vide et ne pousser que le dernier commit (dernier recours)

À privilégier lorsque :

• L’historique source est trop enchevêtré pour être réécrit proprement.
• L’équipe accepte de renoncer à tout l’historique blame/log ; seul l’état actuel compte.
• Cas fréquent pour les projets archivés mis en miroir « pour conservation » et non pour un développement actif.

Procédure :

1. Clonez l’arborescence la plus récente du dépôt source (n’importe quelle branche) dans un répertoire de travail.
2. rm -rf .git && git init && git add . && git commit -m "Initial import: <source-url>@<commit-sha>".
3. Poussez le nouveau dépôt à commit unique vers fremforge selon la procédure standard.
4. Ajoutez un NOTES.md ou un lien CHANGELOG renvoyant vers la source pour tout membre de l’équipe ayant besoin de l’historique complet.

Ce que vous perdez :

• Tout l’historique git blame / git log.
• Tous les diffs historiques de PR / MR (ils restent sur l’hôte source jusqu’à sa suppression).
• Toutes les signatures historiques des commits.

Choisir entre les deux

Choisissez A par défaut, sauf raison sérieuse de faire autrement.

Voir aussi

• Migration depuis GitHub · Migration depuis GitLab · Migration depuis Azure DevOps
• pre-migration-check.sh : parcourt les dépôts source page par page, croise la compatibilité des actions de la Marketplace, met en évidence les configurations de webhooks, de protection des branches et de pipelines. N’effectue PAS d’analyse des secrets dans l’historique (c’est le rôle de gitleaks, à exécuter localement comme décrit sur la page ci-dessus)
• Sécurité et chaîne d’approvisionnement : le hook gitleaks dont parle cette page