Module 1: Why Version Your Workflows

3. The limits of exporting and importing JSON

Next →

Description

By the end of this lesson you will know exactly how a workflow is exported and imported in n8n 2.0 —the menus, the formats, the shortcuts— and, more importantly, you will be able to explain why that way of saving and sharing JSON, which is what almost everyone does, is not version control. You will name the four things export/import does not give you —history, review, rollback, and collaboration— and you will understand the real case, taken from the n8n forum, where the lack of version control drove a team to abandon the tool.

This matters because the most common mistake an automator who "knows they should version" makes is believing they already do. They export their workflows, save them in a folder or in Drive, and feel like the problem is solved. It is not. Confusing "I have copies of the JSON" with "I have version control" is the trap this lesson takes apart, and taking it apart is the required step before Module 2 —where you learn Git— makes sense. If you don't clearly see what export/import is missing, you won't understand what Git comes to solve.

Connection to the module: lesson 1 established that having the file is not having control, and lesson 2 showed why the market pays for control. This lesson is the technical proof of that claim: it shows you in detail what the export/import tool you already use can and cannot do. It's also the bridge to lessons 4 and 5: to understand why copying and pasting JSON fails, you first need to see that the JSON is a text file (lesson 4) and that this text has parts that break when you move it (lesson 5). And it's the direct foundation for lesson 8's project, where you're going to export order-triage with your own hands.

How a workflow is exported and imported, today

Let's start with what the tool does do, because you need to know it well to see where it falls short. In n8n 2.0 there are two ways to get a workflow out of your instance as JSON, and two ways to bring one in.

Exporting to a file. With the workflow open in the editor, at the top right there's a three-dot menu (⋯). Opening it shows the Download option. Choosing it, n8n downloads a .json file to your computer containing the complete workflow: all its nodes, how they're connected, and how each one is configured. That file is the workflow in text form.

Check the label on your panel. This guide was written with n8n 2.x in mid-2026. n8n publishes minor versions almost every week and the interface labels change from time to time —the three-dot menu might be somewhere else, or the option might be named differently in your version. The concept doesn't change: there is a way to download the workflow as a .json file. If you can't find it under this name, look in the workflow menu and confirm against the official documentation for your version.

Exporting by copying to the clipboard. There's an even faster shortcut. If you select all the nodes on the canvas (for example with Ctrl+A) and copy (Ctrl+C), n8n puts the same workflow JSON in your clipboard. You can paste it (Ctrl+V) into a message, a document, or another workflow's canvas. This is how people share workflows on forums and chats: paste the JSON and the other person pastes it into their n8n.

Importing from a file. In the same three-dot menu there's an Import from File option, which lets you choose a .json file from your computer and loads it as a new workflow on your instance.

Importing from a URL or by pasting. There's also Import from URL, to bring in a workflow published at an internet address, and you can paste a copied JSON directly onto the canvas (Ctrl+V), and n8n turns it into nodes.

That's it. Four operations, two outbound and two inbound. It's simple, it works, and it's genuinely useful: this is how templates are shared, how you back up a workflow before a big change, how you move a flow from your machine to a server. There's nothing wrong with the tool. The problem isn't the tool; it's believing the tool is something it isn't.

It's worth understanding when to use each export method, because they aren't interchangeable in practice. Download to a .json file is what you'll use when the workflow's destination is a repository or a backup: it produces a named file, one you can save, version, and open again later. Copying to the clipboard is for quick, throwaway exchanges: pasting it into a message, showing it to someone, moving it between two open workflows. In this guide, the operation you'll use most from here on is Download, because the file is what will later live in the cumbre-automations repository. And one warning that applies to both: what comes out is the workflow as it was saved, not necessarily the last thing you touched in the editor without saving. Save before you export; it's the first stumble for anyone in a hurry.

Having copies is not having versions

Here's the crux of the lesson, and it's worth saying with an image before a definition.

Think about how a lot of people "version" an important document —a thesis, a contract, a proposal— when they aren't using a real tool. They save the file. The next day, before touching it, they make a copy: proposal_v2.docx. Then proposal_v2_revised.docx. Then proposal_FINAL.docx. Then, inevitably, proposal_FINAL_this_one_for_real.docx. After a month they have fourteen files with increasingly desperate names in a folder, and if you ask them "what changed between v2 and v2 revised?", they have to open both and compare them by eye, paragraph by paragraph. And if two people worked on the same proposal, now there are twenty-eight files across two folders, and merging both people's work is a manual nightmare.

That person has copies. They do not have version control. The difference isn't one of quantity —having more copies doesn't bring them closer to control— it's one of nature. A pile of loose photos is not a movie, no matter how many photos you collect.

Real version control is a system that, instead of copies with names, keeps a history. Every time you save a change, the system records three things: exactly what changed (down to the line), who changed it, and why —a note you write. And it keeps that history so you can move through it: see the state from a month ago, compare any two points, go back to either one. A single file with all its history inside, instead of fourteen files with no history.

Exporting your workflow's JSON and saving it in a folder is, exactly, proposal_FINAL_this_one_for_real.json. It's a copy. It can be useful as a one-off backup, but it's not version control, and the difference becomes painful exactly when you need it most: when something broke and you have to go back, or when two people touched the same thing.

Worked example: two people, one workflow, one lost file

Let's see what happens in practice, with Cumbre. The automation team has two people, whom we'll call A and B, and both of them can touch the order-triage workflow. They don't use version control; they use export/import and a shared folder in the cloud. It's Monday.

9:00 — A downloads the workflow. A wants to add a step: new customers' orders should go through an extra validation. They open order-triage in their n8n, do Download, and start working on their local copy.

9:30 — B downloads the same workflow. Without knowing what A is doing, B wants to fix something else: the call to the CRM is using an old field and needs updating. They open the same order-triage, do Download, and start working on their copy.

10:15 — B finishes and uploads. B makes their change in the editor, tests that the CRM call works, and to "back up" does Download and uploads their order-triage.json to the shared folder, overwriting the one that was there.

11:00 — A finishes and uploads. A finishes their new-customer validation, tests it, and uploads their order-triage.json to the shared folder, overwriting B's.

What to expect from this ending: B's CRM fix disappeared. The file left in the folder is A's, which started from the 9:00 order-triage —before B's fix— and doesn't include it. No one deleted it on purpose. No one got a warning. The CRM call is broken again, and the team is going to find out the day an order fails in production, with no clue a change ever got lost.

This pattern has a name: silent overwrite (lost update). It's the number-one failure of "versioning with files." And notice how insidious it is: each person did everything right from their own point of view. A built and tested. B built and tested. Both backed up. The system didn't fail from carelessness; it failed because there was no system. Copying files doesn't coordinate two people; it just gives both of them the illusion that they're backed up.

Now compare it to what would have happened with version control. When A tried to upload their change, the system would say: "wait, B already uploaded a change on top of this same base that you don't have; I can't let you overwrite without reconciling first." A would see B's CRM fix, integrate it with their customer validation, and upload both changes together. Nothing gets lost. That reconciliation —it's called a merge, and it's from Module 2— is exactly what export/import cannot do, because a file that replaces another one knows nothing about the other one.

The four things export/import does not give you

Let's break the general claim down into the four concrete capabilities that are missing. It's worth naming them one by one, because each one is a different reason and each one hurts at a different moment.

1. History: you don't know what changed, when, or why

With export/import, every file is a present with no past. You open order-triage.json and see how the workflow is now, but not how it got there. There's no answer to "since when has this over-5000-pesos condition been there, and who put it in?" The information doesn't exist anywhere: the file only saves the final state, not the path.

Version control saves the path. Every change gets recorded as an entry in a log —a commit, from Module 2— with its date, its author, and your note. You can read the workflow's evolution the way you'd read a patient's medical history: not just how they are today, but everything that happened to them and why. When someone asks "why is this built this way?", the answer is written down, not in your memory.

2. Review: you can't read a change before accepting it

When B sends you their fixed order-triage.json and asks you to approve it, what do you do? You have two giant text files and no convenient way to see what changed between them. Opening them side by side and hunting for the difference by eye is unworkable: a mid-sized workflow is hundreds of lines of JSON, and a one-field change can be buried on line 400.

Version control gives you the diff: a view that highlights exactly the lines that changed, what was removed and what was added, ignoring everything that stayed the same. Instead of hundreds of lines, you see three. You can review a coworker's change —or an AI's, if it helped you edit the workflow, a topic for Module 6— in seconds, and decide with real knowledge whether to approve it. Reading a workflow diff is such a central skill that Module 2 dedicates a whole lesson to it.

3. Rollback: you can't reliably go back to a good version

This is the one that hurts the most. You make a change, turn it on in production, and something breaks. With export/import, your recovery plan is "reimport an old file." But which one? Last week's, if you remembered to download it? Are you sure that one worked? What if the problem wasn't introduced by your last change but by one from three weeks ago that nobody noticed? Without history, rollback is guessing.

Version control turns rollback into a precise operation. Because every version was saved with its date, you can go back to any previous point with the certainty that it's exactly as it was that day. "Put the workflow back to how it was on March 3rd at 14:00" is a command, not an archaeological search through a folder. Module 2 and Module 6 cover rollback in depth; for now, hold on to this: without versioning, rollback is a hope, and with versioning, it's a guarantee.

4. Collaboration: there's no way for two people to work without stepping on each other

This is what you saw in the A and B example. With files, two people touching the same workflow eventually end up, sooner or later, in a silent overwrite. There's no mechanism that detects the conflict or forces reconciliation; whoever saves last wins, and the other person's work evaporates.

Version control was, literally, invented to solve this. It coordinates several people over the same files: it detects when two changes collide, forces them to be merged before continuing, and keeps track of who did what. It's the difference between a team and two people working in parallel with their fingers crossed.

Notice the pattern across the four: history is the past, review is the present before accepting, rollback is undoing, collaboration is working in parallel. Export/import covers none of the four, not because it's poorly made, but because that's not what it's for. It's a transport tool —getting a workflow out and in— not a history-management tool. Confusing one for the other is the mistake this lesson comes to fix.

Worked example: the same change, with files versus with a diff

Let's make the difference between "comparing by eye" and "reading a diff" concrete, because it's the one that gets underestimated the most. Suppose in order-triage you change the manual-review threshold from 5000 to 3000 pesos. In the exported JSON, that change lives inside some decision node, surrounded by a lot of context. A fragment of the file, before:

{
  "parameters": {
    "conditions": {
      "number": [
        { "value1": "={{ $json.order_total }}", "operation": "larger", "value2": 5000 }
      ]
    }
  },
  "name": "Route high-value orders",
  "type": "n8n-nodes-base.if",
  "position": [820, 300]
}

And after the change, the same fragment looks like this:

{
  "parameters": {
    "conditions": {
      "number": [
        { "value1": "={{ $json.order_total }}", "operation": "larger", "value2": 3000 }
      ]
    }
  },
  "name": "Route high-value orders",
  "type": "n8n-nodes-base.if",
  "position": [820, 300]
}

If I give you both complete files —each one with hundreds of lines like these— and ask you to spot the change by eye, you're going to take a while and probably miss it: 5000 and 3000 are two characters in a sea of identical text. That's the world of export/import.

A diff, on the other hand, shows you only this:

-        { "value1": "={{ $json.order_total }}", "operation": "larger", "value2": 5000 }
+        { "value1": "={{ $json.order_total }}", "operation": "larger", "value2": 3000 }

The line starting with - is what was there; the one starting with + is what it became. Everything else —the other three hundred lines that didn't change— the diff hides, because it adds nothing. In two seconds you see what changed, where, and from how much to how much. What to expect once you learn to read diffs in Module 2: reviewing a coworker's change, or one made by an AI that edited the workflow for you, stops being an archaeology task and becomes a glance. That capability —impossible with loose files— is half of why versioning transforms how a team works.

Keep a clue from this for lesson 4: notice the position field in the fragment, that [820, 300]. It's the node's coordinate on the canvas. If you move the node without changing anything about its logic, that number changes and shows up in the diff as if you'd modified something, even though the workflow does exactly the same thing. That's an example of a volatile field, and handling those fields is what separates a readable diff from a wall of noise. Lesson 4 studies them one by one.

The forum case: when the lack of versioning drives people away

This isn't theory. On n8n's official community forum, threads show up now and then where teams explain why they left n8n or why they considered leaving, and among the reasons that repeat there's a concrete phrase: "poor version control."

The typical story behind that phrase goes something like this. A team adopts n8n, builds dozens of workflows, and at some point crosses a complexity threshold where the lack of versioning stops being a nuisance and becomes a risk. Someone breaks a critical workflow and there's no way to reliably go back. Two people overwrite each other's work. Nobody can review anyone else's change before it reaches production. An important workflow behaves differently than it did a month ago and there's no way to know what changed. The team concludes that "n8n doesn't have good version control" and migrates to another tool, sometimes at the cost of months of work.

Here's the honest nuance, and it matters: in most of those cases, the problem wasn't that n8n couldn't be versioned; it was that the team never learned how. Everything that team needed —versioning the JSON with Git, separate environments, diff-based review, rollback— can be done with n8n Community, for free, and it's exactly what this guide teaches. The "poor version control" complaint is, in large part, a complaint about a capability that was available and never used, because nobody explained how.

That's why this guide exists. Not to defend n8n against a criticism, but so that you aren't that team. The difference between "n8n isn't good for serious teams" and "n8n versioned like any professional system" isn't a missing feature: it's the knowledge you're acquiring right now. The export/import tool isn't enough, true. But the fix isn't switching tools; it's adding the discipline this course gives you.

Common mistakes

Believing that backing up is versioning (conceptual). What happens: someone sets up a routine that downloads the JSON of all their workflows every night into a folder, and feels like they already have version control. One day they need to know what changed in a workflow between Tuesday and Thursday, and discover they have two files that look identical with no way to compare them, and no note of what was touched. Why it happens: "backup" and "version control" get used as synonyms, and they aren't. A backup is a copy in case the original is lost; versioning is a navigable history with reasons attached. How to spot it: if your system can't answer "who changed this and why," it's a backup, not versioning. How to fix it: backups have their place —they're the net under the net— but they don't replace versioning. What this guide teaches starting in Module 2 records the why of every change, not just the final state.

Sharing workflows by pasting JSON into a chat as a working method (practical). What happens: a team coordinates changes by sending each other the workflow's JSON over Slack or email —"here's the new version, paste it into your n8n." It works for a one-off template and turns into chaos as a continuous working method: nobody knows which version is the good one, credentials travel pasted into the text, and each person has a different copy. Why it happens: pasting JSON is the easiest thing to do and n8n makes it convenient, so it becomes a habit. How to spot it: if the answer to "what's the latest version of this workflow?" on your team is "I think it's the one so-and-so sent yesterday," you have the problem. How to fix it: a shared repository replaces the chat as the source of truth; everyone starts from the same place and the system coordinates the changes. It's exactly what you set up in Module 2 and structure in Module 3.

Accidentally saving credentials when exporting (practical and security-related). What happens: someone exports a workflow and shares it —posts it to a forum, sends it to a client— without checking whether the JSON includes the names and IDs of the credentials it uses. The IDs aren't secrets, but the names sometimes do reveal information —"Production CRM - Main API Key"— and if the workflow has an HTTP Request node imported from a cURL command, it can carry authentication headers with real secrets inside the JSON. Why it happens: when exporting, you think about the workflow, not about what it drags along with it. How to spot it: open the exported JSON and search for the words credentials, Authorization, apiKey, or token before sharing it. How to fix it: the official documentation explicitly recommends it —strip or anonymize credential names and any authentication headers before sharing a JSON. Clean credential handling outside the workflow is a central topic of this guide: you get introduced to it in lesson 5 and solve it in Modules 3 and 4.

Thinking the problem gets fixed by switching automation tools (conceptual). What happens: a team burned by the lack of versioning concludes n8n "isn't good for teams" and evaluates migrating to another platform, assuming the next one will come with the problem already solved. Why it happens: it's easier to blame the tool than to discover the discipline that was missing, and migration feels like a solution. How to spot it: if your diagnosis is "n8n doesn't have versioning" instead of "I don't know how to version n8n," check the diagnosis. How to fix it: almost every automation platform has the same out-of-the-box limit; serious versioning always gets added with Git around it, it doesn't come magically built in. Learning to do it here helps you regardless of the tool, and saves you a migration that probably wouldn't fix anything.

Exercises

Exercise 1 — Export it and look at the file. Take any workflow you have in your n8n (or build a minimal one with two nodes). Export it with Download. Open the resulting .json file in a text editor and answer for yourself: how many lines does it have? Looking at it, could you tell how it differs from a version you'd exported yesterday? Do you find the word credentials anywhere?

See solution

What most people discover: even a simple workflow generates a file with dozens or hundreds of lines of JSON, with a lot of repetitive structure (node positions, identifiers, parameters). Comparing two of these by eye to find a small change is, in practice, impossible: a single changed value can be surrounded by hundreds of identical lines.

About credentials: if your workflow uses any node with credentials (an HTTP Request, a Gmail node, an AI Agent), you'll find a credentials section with a name and an ID. That's exactly the field you study in lesson 4 and that breaks on reimport in lesson 5.

Why it works: this exercise makes you feel the review problem (capability 2) firsthand. Until you try to spot a change by eye in a real JSON, the claim "you can't review without a diff" is abstract. After trying it, it's obvious. Keep this file: you'll reuse it in lesson 8's project.

Exercise 2 — Diagnose the overwrite. Go back to the A and B example. Write, in your own words, at exactly which moment B's work was lost and why the system didn't warn anyone. Then propose, without using Git yet, a manual process rule the team could follow to reduce the risk, and explain why that rule is fragile.

See solution

B's work was lost at 11:00, when A uploaded their file and overwrote B's. But the root cause was earlier: at 9:30, when B downloaded a copy and started working in parallel with no mechanism in place to record "there are two work branches on top of the same base." The system didn't warn anyone because a folder of files doesn't compare contents or know history: it just keeps the last file that arrives, on top of the previous one.

One possible manual rule: "announce in the team chat before downloading a workflow to edit it, and don't download one that someone else announced they're touching." It reduces the risk, but is fragile for human reasons: someone forgets to announce, two people announce almost at the same time, someone is on vacation and doesn't see the message, or the team grows and the chat becomes unmanageable. It depends on everyone remembering and honoring a convention, which is exactly the kind of guarantee that doesn't scale.

Why it works: the exercise shows you that the collaboration problem (capability 4) doesn't get fixed with human discipline, but with a system that does the coordinating for you. That is precisely why Git exists, and why "announce it in the chat" was never enough on any serious team.

Exercise 3 — Match the pain to the capability. For each of these situations, say which of the four missing capabilities (history, review, rollback, collaboration) is the one that's absent:

(a) "The workflow behaves differently than it did last month and nobody knows what was touched." (b) "My coworker sent me a new version and I have no way to see what changed before accepting it." (c) "I uploaded a change, it broke production, and I'm not sure which old file worked." (d) "We both edited the same workflow yesterday and one of the changes disappeared."

See solution

(a) History. The problem is that there's no record of what changed, when, and why. It's a past with no log.

(b) Review. The problem is not being able to read the change before accepting it; the diff is missing.

(c) Rollback. The problem is not being able to reliably go back to a known good state.

(d) Collaboration. It's the silent overwrite: two changes in parallel with no mechanism to reconcile them.

Why it works: if you were able to match all four without hesitating, you've already internalized that "I don't have version control" isn't a single problem, but four different problems that show up at different moments. Recognizing which one is hurting you at any given moment is what lets you explain the value of versioning with precision —in an interview, or to a boss who doesn't see why it's worth investing time in this.

Summary and next step

In this lesson you saw how a workflow is exported and imported in n8n 2.0 —the three-dot menu with Download and Import from File, the copy-and-paste-the-JSON shortcut— and why that tool, while useful for transporting and backing up, is not version control. You understood that having copies is not having versions: fourteen files with desperate names are not a history, just as a pile of photos is not a movie. You saw, with A and B at Cumbre, how one person's work silently disappears when a team "versions with files" —the silent overwrite— and you broke down the four capabilities export/import does not give you: history (what changed and why), review (reading a change before accepting it, with a diff), rollback (reliably returning to a good state), and collaboration (making sure two people don't step on each other). And you saw the real forum case, where the "poor version control" complaint drove away teams that actually had the free solution available and never used it.

Before moving on you should be able to: describe the two ways to export and the two ways to import in n8n; name the four missing capabilities and one concrete pain point for each; and explain in one sentence why "backing up" is not "versioning."

What's next is opening the file we've mentioned so much. Up to now we've talked about the workflow's JSON as a closed box of "hundreds of lines." Lesson 4 opens it: you're going to see exactly what's inside —the nodes, the connections, the configuration, the identifiers, the credential references— and you're going to learn to tell stable fields apart from volatile ones. That distinction isn't a technical footnote: it's what decides whether a diff of your workflow is readable or a wall of noise, and it's the foundation for understanding, in lesson 5, exactly what breaks when you move that file from one instance to another.

Resources

← Previous2. Workflow builder vs system ownerNext →4. Anatomy of a workflow JSON