Historique des versions n8n : restaurer un workflow cassé sans paniquer

Le scénario est toujours le même. Un workflow tourne en production depuis des mois, quelqu'un ouvre l'éditeur pour « juste ajuster un champ », et dans l'heure qui suit les alertes tombent. n8n conserve bien un historique des versions, avec prévisualisation et bouton de restauration — mais la rétention dépend du plan, elle est plus courte qu'on ne l'imagine, et une restauration ne répare pas tout. Ce guide couvre l'urgence, puis la prévention.

Ce que n8n enregistre, et quand

D'après la documentation, n8n crée une nouvelle version dans trois cas :

• quand vous enregistrez le workflow — l'éditeur enregistrant désormais automatiquement au fil des modifications, comme le détaille le guide save & publish de n8n 2.0 ;
• quand vous restaurez une ancienne version : n8n enregistre l'état courant avant de restaurer, ce qui laisse une porte de sortie ;
• quand vous faites un pull depuis un dépôt Git via Source control — ces versions sont écrites dans la base de l'instance, pas dans Git.

Point souvent ignoré : les modifications des réglages du workflow ne créent pas de version. Changer le timezone ou l'error workflow ne laisse aucune trace.

À ne pas confondre avec les exécutions, qui sont des runs de la version courante, qu'on rejoue pendant le débogage d'un workflow. Une version d'historique, elle, stocke la liste complète des nodes, les connexions, l'auteur et l'horodatage.

Où le trouver et ce qu'on peut en faire

Cliquez sur l'icône Workflow history dans l'en-tête du workflow. n8n affiche un panneau listant les versions enregistrées, et le canvas bascule en prévisualisation : vous voyez le graphe tel qu'il était, sans rien modifier. Sur chaque version, le menu Options propose cinq actions :

• Restore version : remplace le workflow courant par la version sélectionnée ;
• Clone to new workflow : crée un nouveau workflow à partir de cette version ;
• Open version in new tab : ouvre un second onglet, pour comparer côte à côte ;
• Download : télécharge la version au format JSON ;
• Name version : nomme et décrit la version, qui devient protégée de la purge automatique (disponible sur Cloud Pro, Enterprise et self-hosted Enterprise).

Le réflexe en production n'est pas « Restore » mais « Clone to new workflow » : vous obtenez une copie inactive, vous la comparez au workflow cassé, et vous ne basculez qu'une fois certain.

La rétention dépend du plan

Pas d'illusions ici. La documentation n8n annonce trois niveaux : 24 heures de versions pour tous les utilisateurs, 5 jours sur n8n Cloud Pro, historique complet sur les plans Enterprise, en Cloud comme en self-hosted.

Une instance Community auto-hébergée vit donc avec une fenêtre de 24 heures : de quoi rattraper l'erreur de la veille, pas de quoi retrouver « la version qui marchait avant les vacances » — une limite à ranger avec les autres arbitrages du guide des limites de n8n gratuit.

Les variables d'environnement du self-hosted

Une seule variable est aujourd'hui documentée pour l'historique :

# Durée de conservation des versions, en heures.
# -1 (valeur par défaut) = conserver toutes les versions indéfiniment.
N8N_WORKFLOW_HISTORY_PRUNE_TIME=-1

Le piège est dans l'interaction avec la licence : dans le code de n8n, la durée effective est le minimum entre la limite de licence et la valeur de configuration, -1 valant « infini » des deux côtés. Si la licence plafonne à 24 heures, laisser -1 ne change rien. À l'inverse, sur une instance Enterprise, 720 (30 jours) bride volontairement la croissance de la base.

Un détail à signaler, parce qu'il traîne encore dans beaucoup de fichiers docker-compose.yml : N8N_WORKFLOW_HISTORY_ENABLED, qui valait true par défaut et coupait l'enregistrement des versions, existait en 1.x mais a disparu du code en 2.0. Si vous la trouvez, elle n'a plus d'effet — le genre de résidu que l'on traque en relisant son inventaire de variables d'environnement.

Le coût en base de données

Chaque version est un enregistrement complet : nodes et connections sérialisés en JSON, plus les métadonnées. Un workflow de trente nodes avec des prompts IA longs pèse plusieurs centaines de kilo-octets par version. Multipliez par une journée d'édition intensive et par le nombre de workflows : l'historique devient une table à surveiller au même titre que celle des exécutions, avec le même raisonnement que pour le nettoyage des exécutions n8n. Et il vit dans cette base : il ne remplace pas une sauvegarde PostgreSQL. Perdre la base, c'est perdre les workflows et leur historique.

Ce que l'historique ne restaure pas

C'est ce qui explique la plupart des restaurations « qui ne marchent toujours pas » : une version contient la structure du workflow, et rien d'autre. Ne reviennent donc pas :

• les credentials, référencées seulement par identifiant et par nom : si l'une a été supprimée ou re-scopée, la version restaurée pointe dans le vide ;
• les données d'exécution : restaurer ne rejoue rien ;
• les variables d'instance, qui ne sont pas versionnées avec le workflow ;
• les sous-workflows appelés par un node Execute Sub-workflow, qui ont leur propre historique. Restaurer le parent sans l'enfant produit une combinaison qui n'a jamais existé ;
• les réglages du workflow, on l'a vu, qui ne créent même pas de version.

Cette dissociation entre l'artefact et son environnement est un classique de la fiabilité des systèmes. Dans « An Empirical Study on Configuration Errors in Commercial and Open Source Systems », publié en 2011 à SOSP, Zuoning Yin et ses coauteurs analysent 546 erreurs de configuration réelles, dont 309 issues d'un système de stockage commercial déployé chez des milliers de clients, et montrent que 70 à 85 % d'entre elles proviennent d'erreurs sur les paramètres eux-mêmes (voir sur Google Scholar). Transposé à n8n : un workflow correct pointant vers une credential incohérente casse aussi sûrement qu'un workflow bogué.

Mode opératoire d'urgence

1. Désactivez le workflow (ou dépubliez-le) : tant qu'il tourne, chaque exécution aggrave les effets de bord.
2. Ouvrez l'historique et repérez l'horodatage juste avant la modification fautive ; l'auteur affiché vous dit qui a touché à quoi.
3. Prévisualisez la dernière version saine sur le canvas, sans rien restaurer.
4. Clonez-la via Clone to new workflow : vous disposez alors de la copie saine et du workflow cassé, côte à côte.
5. Comparez les deux JSON hors de n8n (voir ci-dessous) : c'est l'étape qui évite de réintroduire une régression avec le correctif.
6. Basculez, puis revérifiez les credentials avant de réactiver.

Comparer deux versions avec diff et jq

Le canvas repère très bien un node manquant, très mal un paramètre modifié dans un node parmi trente. Récupérez le JSON de la version saine via Download, et celui de la version courante via l'API REST de n8n ou l'export manuel du workflow :

# Version courante, via l'API publique
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "https://n8n.example.com/api/v1/workflows/AbCdEf123456" > courant.raw.json

# Normalisation : on ne garde que ce qui compte, trié par nom de node.
# Les positions sur le canvas et les identifiants internes ne sont que du bruit.
NORM='{nodes: [.nodes[] | {name, type, typeVersion, parameters, credentials}] | sort_by(.name), connections}'

jq -S "$NORM" courant.raw.json   > courant.json
jq -S "$NORM" version-saine.json > saine.json

diff -u saine.json courant.json

Sans l'étape jq, un simple déplacement de node à la souris produit des dizaines de lignes de différences et noie le vrai changement. Avec elle, le diff tient souvent en cinq lignes.

Les pièges

• Compter sur un historique qui n'existe pas. Sur une instance Community, la fenêtre est de 24 heures. Le jour où vous en avez besoin, il est trop tard pour changer de plan ;
• Restaurer une version qui référence une credential supprimée. Les appels échouent en authentification et personne ne comprend pourquoi « la bonne version » ne marche pas. Rouvrez le node et resélectionnez la credential ;
• Croire que restaurer annule les effets de bord. Les 4 000 emails déjà partis ne reviennent pas. C'est le vrai argument pour concevoir des workflows idempotents plutôt que pour se rassurer avec un bouton de rollback ;
• Supprimer ou archiver le workflow. L'historique lui est lié par une suppression en cascade : le workflow part, ses versions partent avec lui ;
• Éditer à plusieurs sans se prévenir. n8n ne laisse qu'une personne éditer à la fois et bascule les autres en lecture seule, mais rien n'empêche deux collègues de se relayer en une heure et de produire un historique illisible ;
• Confondre historique et sauvegarde. Purgé automatiquement, stocké dans la base, dépourvu de credentials : ce n'est pas un plan de reprise.

La vraie prévention, en trois niveaux

L'historique est un filet de sécurité, pas une stratégie. Trois pratiques réduisent le besoin d'y recourir :

1. Versionner les workflows dans Git, en exportant leur JSON via l'API n8n — le sujet du guide sur la sauvegarde et le versionnement des workflows n8n dans Git. Historique illimité, git blame, revue de code ;
2. Séparer développement et production, pour qu'une modification n'atteigne jamais directement le workflow qui tourne — la démarche décrite dans le guide des environnements dev/prod avec n8n ;
3. Valider avant de déployer, avec des contrôles automatiques sur le JSON exporté, comme dans le pipeline de validation de workflows n8n en CI avec GitHub Actions.

Ce n'est pas de la sur-ingénierie. Dans « When do changes induce fixes? », publié en 2005 aux Mining Software Repositories (ACM SIGSOFT Software Engineering Notes), Jacek Śliwerski, Thomas Zimmermann et Andreas Zeller ont analysé les archives de Mozilla et Eclipse pour identifier les changements qui provoquent ensuite des correctifs, et montré que ces changements « fix-inducing » suivent des régularités nettes, notamment quant à leur taille et au jour de la semaine où ils sont appliqués (voir sur Google Scholar). Leur méthode, devenue l'algorithme SZZ, repose entièrement sur l'existence d'un historique exploitable : sans trace des changements, impossible de remonter à la cause. Un workflow modifié directement en production un vendredi soir coche toutes les cases.

En résumé

L'historique s'ouvre depuis l'icône Workflow history et propose Restore version, Clone to new workflow, Open version in new tab, Download et Name version. En self-hosted, il se règle avec N8N_WORKFLOW_HISTORY_PRUNE_TIME (en heures, -1 pour tout garder, sous réserve de la limite de licence). Trois chiffres à retenir : 24 heures pour tout le monde, 5 jours sur Cloud Pro, historique complet en Enterprise. Et une limite conceptuelle : restaurer un workflow ne restaure ni ses credentials, ni ses variables, ni ses sous-workflows, ni les effets de bord déjà produits. En urgence, clonez avant de restaurer. Le reste du temps, mettez vos workflows dans Git.

Pour aller plus loin

La discipline de version compte double sur les workflows qui touchent à des données sensibles ou à des obligations de traçabilité. Le Pack Conformité & Audit (149 €) est bâti sur cette logique : des workflows dont chaque exécution laisse une preuve, et dont les modifications doivent pouvoir être justifiées après coup. Si vous industrialisez plusieurs chaînes en parallèle, le Bundle FlowKit Complet (269 €) fournit un socle de workflows déjà structurés, prêts à être exportés et versionnés dès le premier jour.