Le format .n8np dans n8n 2.x : empaqueter et migrer plusieurs workflows en un seul fichier

Jusqu'ici, migrer plusieurs workflows n8n liés d'une instance à une autre imposait de les exporter un par un (voir notre guide de l'import/export JSON), de recréer chaque crédentiel à la main, et de croiser les doigts pour que rien ne manque. n8n 2.x introduit un format dédié à cet usage : le package .n8np, qui embarque plusieurs workflows, leurs dépendances de crédentiels et un manifeste dans un seul fichier portable. Ce guide détaille sa structure, les commandes n8n-cli pour créer et importer un package, et les pièges à connaître — notamment la gestion des secrets, un sujet que l'étude de Michael Meli, Matthew McNiece et Bradley Reaves présentée à NDSS en 2019 (« How Bad Can It Git? Characterizing Secret Leakage in Public GitHub Repositories », voir sur Google Scholar) a chiffré à plus de 100 000 dépôts GitHub touchés et des milliers de nouveaux secrets exposés chaque jour — exactement le type de fuite que le design des packages .n8np cherche à rendre impossible par construction.

Le problème que .n8np résout

L'export JSON classique — un fichier, un workflow — fonctionne bien pour partager un template isolé. Il montre vite ses limites dès qu'un cas d'usage repose sur plusieurs workflows interdépendants : un flux principal et ses sous-workflows appelés via Execute Workflow (voir notre guide pour découper des workflows complexes en sous-workflows), un trigger et le workflow de traitement qu'il déclenche, ou un ensemble cohérent façon pack, comme ceux que vend FlowKit (tri d'emails, priorisation, digest et brouillons pour le Pack Inbox IA, par exemple). Sans structure de package, il faut soit exporter chaque fichier séparément et les réimporter dans le bon ordre, soit tout regrouper à la main dans une archive maison en espérant ne rien oublier — dépendances de crédentiels comprises. .n8np formalise cette opération.

Anatomie d'un fichier .n8np

Techniquement, un package .n8np est une archive tar non compressée : l'extension est une simple convention, n8n ne vérifie pas le nom de fichier à l'import et accepte n'importe quel tar respectant la même structure. En l'extrayant, on trouve :

• un manifest.json à la racine, qui indexe le contenu du package et doit être le tout premier fichier de l'archive — c'est ce qui permet à n8n de valider un package avant même de lire le reste ;
• un dossier workflows/ où chaque workflow est son propre petit fichier JSON, dans son propre sous-dossier ;
• les stubs de crédentiels référencés par ces workflows (voir plus bas).

Cette granularité — une entité, un fichier — rend le contenu d'un package lisible et diffable dans Git, contrairement à un export monolithique.

Créer un package avec n8n-cli

Sur une instance self-hosted, la commande d'export prend soit une liste de workflows précis, soit un projet entier :

# Empaqueter un ou plusieurs workflows précis
n8n-cli package export --workflow-id=<id-1> --output=export.n8np

# Empaqueter tous les workflows d'un projet
n8n-cli package export --project-id=<project-id> --output=project.n8np

--output peut être omis (il vaut export.n8np par défaut). Cette approche par identifiant en fait un mécanisme automatisable : un job planifié qui régénère un package à chaque changement, une étape de build qui produit un artefact de déploiement, ou — cas d'usage direct pour qui distribue des workflows en marque blanche à des clients — un script qui empaquette la version courante d'un pack avant chaque livraison.

Importer un package sur une autre instance

L'import exige de trancher un point que l'ancien export/import JSON laissait implicite : que faire si un workflow du même identifiant source existe déjà côté cible ?

n8n-cli package import --file=export.n8np --workflow-conflict-policy=fail

n8n-cli package import --file=export.n8np \
  --project-id=<project-id> --workflow-conflict-policy=skip

--workflow-conflict-policy est obligatoire et accepte trois valeurs : fail (l'import s'arrête, le choix le plus sûr pour une première migration), skip (les workflows déjà présents sont ignorés) et new-version (une nouvelle version du workflow existant est créée — utile pour un redéploiement contrôlé, voir notre guide de l'historique et de la restauration de versions). Ce paramètre explicite remplace l'écrasement silencieux par identifiant qui pouvait surprendre avec la CLI d'export/import classique.

Les stubs de crédentiels : jamais de secret dans le fichier

Comme pour l'export JSON standard, un package .n8np n'embarque jamais la valeur d'un crédentiel. Il exporte un stub — identifiant, nom et type — que l'instance cible doit rattacher à un crédentiel réel. Deux modes gèrent cette résolution à l'import :

• create-stub (comportement par défaut) : n8n crée un crédentiel vide et provisoire dans le projet cible. Le workflow s'importe, mais reste non publiable tant que le crédentiel n'a pas été renseigné manuellement — un garde-fou qui évite qu'un workflow tourne silencieusement sans les bonnes clés API.
• must-preexist : l'import échoue si un crédentiel référencé n'existe pas déjà sur l'instance cible — le choix le plus strict pour un déploiement vers un environnement de production déjà provisionné (voir notre guide des environnements dev/prod).

Pour éviter de recréer manuellement chaque crédentiel un par un, un remappage explicite peut être fourni sous forme d'un objet JSON associant les identifiants du package à ceux de la cible :

{"credentials": {"<id-credential-dans-le-package>": "<id-credential-sur-la-cible>"}}

Ce mécanisme de stub plutôt que de valeur en clair est exactement la bonne pratique que l'étude de Meli et ses co-auteurs appelle de ses vœux : sur les dépôts GitHub qu'ils ont analysés, la fuite de secrets vient presque toujours d'un fichier de configuration ou d'export commité tel quel, avec ses clés en clair dedans. Un package .n8np versionné dans Git ne peut structurellement pas reproduire ce risque, pour peu qu'on ne remplace pas un stub par un vrai secret au dernier moment. Pour durcir encore la gestion des accès, voir notre guide de sécurisation des crédentiels et de l'API n8n.

Le piège du modèle publish/unpublish (n8n 2.0)

n8n 2.0 a remplacé la simple bascule actif/inactif des workflows par un modèle publish/unpublish, piloté en CLI par publish:workflow et unpublish:workflow. Un workflow importé depuis un package n'est donc pas automatiquement en production : selon l'état du crédentiel (stub non résolu ou non), il peut rester bloqué en état non publiable. Vérifiez systématiquement l'état de publication après un import — un import « réussi » en apparence qui ne tourne pas encore est le piège classique de toute migration, comme le rappelle notre guide des évaluations et tests de workflows.

.n8np, export JSON ou Git : quand utiliser quoi

• Export JSON simple : partager un workflow isolé, un template, un dépannage ponctuel — voir le guide complet import/export.
• Git + CLI classique (export:workflow --separate) : source de vérité versionnée, historique complet, revue de code sur chaque changement — la stratégie recommandée pour versionner ses workflows.
• Package .n8np : déplacer un ensemble cohérent de workflows entre instances en une seule opération — mise en place d'un nouvel environnement, livraison d'un pack à un client, migration entre instances self-hosted, après une mise à jour majeure.

Les trois se combinent : un package .n8np généré depuis un pipeline de build reste tout à fait versionnable dans Git en parallèle, comme artefact de release plutôt que comme source de vérité au jour le jour.

Distribuer des workflows en équipe : le bon réflexe

Si votre organisation maintient plusieurs workflows liés — un flux principal et ses sous-workflows, un trigger et son traitement, un ensemble cohérent façon pack — le format .n8np évite l'export/import fichier par fichier et la resynchronisation manuelle des crédentiels à chaque migration. C'est exactement le problème que nos packs FlowKit résolvent au niveau produit : plusieurs workflows liés, un guide d'installation unique, des crédentiels clairement identifiés par node. .n8np apporte la même logique côté outillage natif n8n, pour vos propres workflows internes.