1. Introduction: Git applied to workflows

Description

By the end of this lesson you will be able to explain why Git —and not a folder of copies, not Dropbox, not n8n's save button— is the right tool for keeping a workflow's history, you will be clear on what we are NOT assuming (we start from zero, without a single line of prior Git experience), and you will know the complete thread running through this module's eight lessons: the same Cumbre workflow, order-triage, which you're going to put under version control step by step, from your first git init to pushing it to a shared remote on GitHub and recovering a version that used to work.

This matters for a very concrete and very unromantic reason: the market. When you look at the best job postings that mention n8n, some of them ask, in these exact words, for workflows delivered "as version-controlled, documented JSON." It doesn't say "know how to build workflows"; that's assumed. It says you know how to treat them as an asset that has a history, that gets reviewed, that can go back to a previous state without drama. That phrase is, word for word, the border between the workflow builder and the automation system owner we saw in Module 1. And on the other side of that border, the tool the market takes for granted is called Git.

Connection to the module: this lesson is the map, not the terrain. You're not going to type a single Git command on your machine yet; here you define the problem (why improvised history isn't enough), get a bird's-eye view of the tool, and receive the plan for the seven lessons that follow. Lesson 2 installs Git for you and creates your first repository. Lessons 3 through 5 are the heart of the daily cycle: making commits, reading diffs, and working in branches. Lessons 6 and 7 close with the shared backup on GitHub and recovering earlier versions. And lesson 8 pulls it all together into a project: order-triage with a readable history, iterated across several branches and with a change cleanly reverted. One limit worth stating now, because teaching too much confuses just as much as teaching too little: you won't see interactive rebase here, or submodules, or the branching strategies of a fifty-person team. Just the Git a workflow's lifecycle needs. Not one command more.

The real problem: order-triage-final-final-v2-OK.json

Let me describe a scene you've probably already lived, even if with a different kind of file.

You have a workflow that works. You export it "just in case" and save it as order-triage.json. The following week you make a change to it, and since you don't want to lose the one that already worked, you save the new one as order-triage-v2.json. A month later there's order-triage-v2-priority.json, order-triage-GOOD.json, order-triage-final.json, and —the classic— order-triage-final-final-v2-OK.json. Someone on the team has their own folder with their own version. And the day production breaks and someone asks "which one was working last Tuesday?", nobody knows the answer for sure. They open three files, compare them by eye, and guess.

That chaos has a technical name: lack of version control. And the uncomfortable part is that almost all of us solve it badly the same way —with hand-dated copies— because it feels like the natural thing to do. The problem is that method fails exactly when you need it most: it doesn't tell you what changed between one version and another, it doesn't tell you who changed it or why, it doesn't let you work on something new without risking what already works, and when you need to go back, going back means "open old files and pray."

Think of it as the difference between a drawer full of loose photos and an album. In the drawer you have the photos, sure, but you don't know what day each one is from, in what order things happened, or which comes after which. The album has the same photos, but each one with its date, in order, with a note of what was going on. Git is the album. Every version of your workflow gets its date, its author, a note of what changed, and its exact place on the timeline.

Why Git and not Dropbox, Google Drive, or n8n's history

It's a fair question, because those tools also "save versions." It's worth being honest about what each one does and why none of them substitute for Git here.

Dropbox and Google Drive save versions automatically, that's true. But they save versions of a whole file, not of an intentional change. They don't let you say "these five modifications go together because they solve the same problem, and this note explains why." They don't let you work on two different ideas at the same time without them stepping on each other. And their version comparison, when it exists, isn't built to read the real change inside a structured text file like a workflow's JSON. They're excellent for backing up; they're poor for understanding the evolution of something.

n8n's execution and version history is useful inside the platform, and on the paid editions there's native version control, which we discuss honestly in Module 6. But on the Community edition —this guide's default starting point, at zero cost— that history lives tied to the instance. If the instance gets corrupted, if you migrate servers, if you want the history outside n8n to review it, share it, or feed it into a team review process, you need something independent of the platform. Git is exactly that: the history lives in a folder that's yours, one you can copy, move, and back up wherever you want.

Git, on the other hand, was designed from day one for one thing: keeping the history of text files in a way that lets you see what changed line by line, group changes with an explanation, work in parallel without fear, and go back to any earlier point with surgical precision. An exported n8n workflow is a text file —JSON. It fits Git like a glove. With one important caveat we'll face head-on in lesson 4, and that Module 3 finishes solving: that JSON, as it comes out of n8n, isn't the friendliest text file in the world for Git. But that has a fix, and the fix is part of what you learn here.

One clarification that heads off a classic confusion right now: Git is not GitHub. Git is the program that runs on your machine and keeps the history. GitHub is a website where you can host a copy of that history to back it up and share it. You can use Git for years without ever touching GitHub. We're going to use Git starting in lesson 2, and GitHub doesn't show up until lesson 6, once it makes sense. If you've ever heard "push your code to Git" and gotten confused, this was it: people mix the two names all the time, and now you won't.

Worked example: what the destination looks like

Before installing anything, it's worth looking at where we're headed. This is what you're going to be able to produce by the end of the module: order-triage's history seen through a Git command that shows the list of versions, one per line. Don't run it yet —you don't have Git set up or the repository created— read it the way you'd read a furniture box's photo before assembling it.

# The command that shows the summarized history, one version per line.
git log --oneline

What to expect when you reach lesson 8 and run that on your Cumbre repository:

d4f9a1c Revert "Point CRM lookup at the staging URL"
7b2e105 Point CRM lookup at the staging URL
a91c3f8 Add wholesale category to the order classifier
3e5d720 Widen CRM lookup timeout to 15 seconds
c08b4a2 Add order-triage workflow

Pause for a second on what you're looking at, because this block contains, in miniature, everything the module teaches.

Each line is a saved version of the workflow —in Git it's called a commit, and it's lesson 3's concept. They're read from bottom to top, from oldest to newest. The bottom one, c08b4a2 Add order-triage workflow, is day one: the moment order-triage entered Git. The ones above are later changes: the CRM lookup's timeout got widened, a "wholesale" category got added to the order classifier, the CRM lookup got pointed at a test URL.

The odd-looking code at the start of each line —c08b4a2, 3e5d720— is that version's unique identifier. Think of it as a document's file number: it never repeats, and with it you can refer to exactly that version with no ambiguity. Yours will be different from these; Git generates them, you don't choose them.

And notice the last line, the topmost one: Revert "Point CRM lookup at the staging URL." Someone pointed the CRM lookup at the test URL —probably by mistake, or to test something— and then undid it cleanly and on the record. They didn't delete anything, didn't open an old file: they left a record that this change was reverted, with a date and an author. That's lesson 7, and it's the difference between "I had an old JSON lying around somewhere" and an auditable recovery.

The whole module is learning to produce and read that block of text. Nothing more, and nothing less.

The module's thread: Cumbre's order-triage

As throughout the whole guide, we work on the same fictional company so as not to burn energy relearning the context in every lesson. If you're coming from Module 1 you already know it; if you landed directly here, this is the summary you need.

Cumbre is a Latin American wholesale distributor of coffee and tea. It sells to cafés and small shops, and since it's a small team, it automates so it doesn't have to process orders by hand. The workflow we're going to work with throughout the module is called order-triage, and it does three things:

1. Receives incoming orders, through a Webhook node.
2. Classifies them with an AI Agent node, which reads the order and decides which category it falls into —for example standard, priority, or wholesale.
3. Queries the CRM over HTTP, with an HTTP Request node, to pull customer data and decide how to route the order.

You're not going to build order-triage in this module —building workflows is the subject of other guides in the ecosystem, and here it's assumed you already know how to do it. You're going to do something different and, for the market, more valuable: you're going to put it under version control. In Module 1 you exported it as a JSON file; in this module that file is going to live inside a folder called cumbre-automations, and that folder is going to turn into a Git repository.

Here's the complete arc, lesson by lesson, so you see it isn't eight separate topics but a single motion:

Lesson	What happens to order-triage
2	You install Git and turn the cumbre-automations folder into a repository. The workflow doesn't have history yet, but now it has somewhere to keep one.
3	You take the workflow's first "photo": your first commit. And you learn to take clean photos, with good notes.
4	You change something in order-triage, export it again, and learn to read what changed by comparing the two versions.
5	You try out a new idea —an additional classification category— on a separate branch, without risking the version that works.
6	You push the entire history to GitHub, to back it up and so another team member can work on it.
7	A change broke the workflow. You go back to the version that worked, on the record and without drama.
8	The project: you put everything above together into a deliverable repository, with a readable history and one cleanly reverted change.

If you notice, it's the complete life of a change in a professional workflow: it gets saved, compared, tried out separately, shared, and —when something goes wrong— reverted. That's what an automation system owner does, and that's what you're going to know how to do by the end of Module 2.

Two Tuesdays at Cumbre: the real cost of not versioning

Abstract arguments don't convince much. Let's look at the same problem in two versions of Cumbre: one without Git and one with Git. The situation is identical in both, and it's the kind that really happens on any given Tuesday.

The trigger. Someone —you, or a teammate— touches order-triage to "improve" something. They change the classifier's category, tweak the CRM URL, or move two nodes around. They save, publish, and go to lunch. At three in the afternoon, wholesale-channel orders stop routing correctly: they all fall through as standard and the warehouse team can't see the priorities. Something from this morning's change broke it.

Cumbre without Git. The workflow running in production is the only one that exists; the "previous" one, at best, sat in an order-triage-backup.json file someone saved three weeks ago —or nobody saved it at all. Archaeology begins: what exactly got changed today? Nobody's sure. The editor gets opened, the workflow gets looked at, and someone tries to remember how it was this morning. Three things get tried by trial and error. One of them seems to fix it, but nobody knows if it fixed the cause or just covered the symptom, and since other nodes got touched in the process, there are now two unrecorded changes on top of the one that broke things. If the three-week-old backup exists, going back to it also means losing the good improvements from those three weeks. The incident closes at night, with a workflow that "seems to work" and an ugly feeling of not knowing why it broke or why it got fixed.

Cumbre with Git. This morning's change is a commit, with its note and its author. When wholesale orders stop routing, the first command tells the story: git log shows that today at 9:40 someone made Point CRM lookup at the staging URL, and that before that the workflow had been stable for two weeks. git diff between yesterday's version and today's shows, in three lines, exactly what changed: the CRM URL now points at the test server, which doesn't have the wholesale customers' data. The cause is known in thirty seconds. That commit —only that one— gets reverted with git revert, and the workflow goes back to the state that worked, without losing any of the good improvements from previous weeks, and leaving a record that this change was undone and why. The incident closes in ten minutes, and the team learns something concrete from it instead of being left with a mystery.

The difference between the two Tuesdays isn't that one team is smarter than the other. It's that one has the album with dates and notes, and the other has the drawer of loose photos. With the same people, the same hands, and the same mistake, the outcome changes completely depending on whether or not there's a history you can interrogate.

And there's a second, quieter cost that the bad Tuesday hides: fear of touching things. At Cumbre without Git, after a scare like that, people stop improving the workflow out of fear of breaking it again with no way back. The system freezes. At Cumbre with Git, since any change can be precisely reverted, people experiment calmly —on branches, as you'll see in lesson 5— and the workflow keeps evolving. Version control doesn't just save you from mistakes: it gives you back the freedom to improve without fear. That is, in the end, this module's biggest gift.

What we assume and what we don't

It's worth being explicit, because the most common fear when arriving at Git is "this is for real programmers, not for me."

We don't assume you know Git. Not a single command. You don't know what a commit is, or a branch, or a repository. All of that gets defined from zero, with analogies, before it's used. If at any point a term sounds like jargon, that's a mistake in this guide, not a failure on your part.

We don't assume you're a programmer. You came to n8n for automation, not for programming, and that's perfectly fine. Git isn't programming: it's keeping the history of files. A writer, a designer, or a lawyer could use Git for their documents just as usefully. It just happens that the people who get the most out of it are the ones who work with text files that change over time, and an exported workflow is exactly that.

We do assume three minimal things, all from ground you've already covered: that you've built real workflows in n8n and feel comfortable in the 2.0 editor; that you know how to export a workflow to JSON (you did that in Module 1); and that you can open a terminal on your machine and type a command. If that last one makes you nervous, relax: lesson 2 starts right there, with the most basic terminal, and you're not going to need anything more advanced than typing a command and reading what comes back.

A promise worth making early: by the end of this module you're not going to "know Git" in the sense of mastering its two hundred commands —nobody masters them, not even the experts. You're going to know the eight or nine used 95% of the time to keep a workflow's history, and you're going to know them well, understanding what each one does underneath. That's more than enough to cross into the professional side, and it's more than what many self-declared "Git users" actually understand.

A glimpse of the vocabulary ahead

We're not going to fully define anything yet —each term has its own lesson— but it's worth these words not catching you by surprise when they show up. Think of this list as the cast of characters at the start of a novel: you don't have to memorize it, just know it's there to come back to.

• Repository (repo): your project's folder once Git is keeping its history. Lesson 2.
• Commit: a saved snapshot of the project at a given moment, with a note, date, and author. Lesson 3.
• Staging (staging area): the place where you choose what is going into the next snapshot, before taking it. Lesson 3.
• Diff: the comparison that shows you what changed between two versions, line by line. Lesson 4.
• Branch: a parallel line of work where you can experiment without touching the good version. Lesson 5.
• Merge: the act of bringing a branch's changes back into the main one. Lesson 5.
• Remote: a copy of your repository hosted somewhere else, like GitHub, for backup and shared work. Lesson 6.
• Revert / rollback: undoing a change and going back to an earlier version, on the record. Lesson 7.

Eight words. That's almost the entire vocabulary separating someone who versions their workflows from someone who saves them as final-final-v2. It's not that much.

About the black terminal, before it scares you

Starting in lesson 2 you're going to type Git commands into a terminal —that dark-background window where you type and the machine responds with text. For a lot of people who came to automation through n8n's visual canvas, that window produces an almost physical rejection: it looks intimidating, it looks "hacker-ish," it looks like the place where one wrong command wipes your hard drive. It's worth defusing that fear now, because it's unfounded and it's going to get in your way.

The terminal is, simply, a way of giving the machine orders by typing instead of clicking. Nothing more. When you type git status and press Enter, you're asking Git "how's my project doing?", the same way you would by clicking a button that says "Status." The only difference is that instead of a button, you type a word. And the Git commands you're going to use are read and save orders, not destroy ones: git status, git log, git diff only look and don't change anything; git add and git commit save; the few commands that can actually delete work —you'll see them in lesson 7— come with a big warning and a safe alternative.

Think of it like learning to order coffee in another language. The first time, saying "a coffee with milk, please" in a new language is nerve-wracking and comes out choppy. By the tenth time, you say it without thinking. Git commands are that handful of phrases: at first you copy them carefully, and in two weeks you type them from memory without noticing. You don't need to understand the whole grammar of a language to order coffee. You don't need to "know the terminal" to use Git.

One habit that's going to serve you for life and starts here: when a command gives you back text you don't understand, don't ignore it and don't panic. Read it. Git is surprisingly chatty: when something goes wrong, it almost always tells you what happened and even suggests the command to fix it. You'll see examples of that in every lesson. The terminal isn't your enemy; it's the most honest conversation partner you're going to have.

Common mistakes

Believing Git is only for programmers (conceptual). What happens: someone looks at Git, sees commands in a black terminal, and concludes "this isn't for me, I do automation without code." Why it happens: Git was born in the world of software development and almost all its material is written for programmers, with code examples in languages an automator doesn't use. That presentation creates the illusion of a programming prerequisite that doesn't actually exist. How to spot it: if your reason for not using Git is "I don't know how to program" and not "I don't need it," this is the confusion. How to fix it: remember what Git actually does —it keeps the history of text files— and that an exported workflow is a text file. You don't need to write code to version a file; you need to learn eight commands, which is what this module does. The barrier is one of presentation, not of difficulty.

Confusing Git with GitHub (conceptual). What happens: the two names get used as synonyms —"push this to Git," "my code is on Git"— and then misunderstandings follow about what you need to get started. Why it happens: most people learn about Git through GitHub, so they associate the two names as if they were one. How to spot it: if you think you need an account on some website to start versioning, you have the concepts mixed up. How to fix it: hold on to the separation —Git is the local program that keeps the history; GitHub is an optional site to host a copy. You're going to use Git alone on your machine for four lessons before GitHub even shows up. You don't need an account for anything in lesson 2.

Thinking exporting and importing JSON is already "versioning" (conceptual). What happens: someone exports their workflow every so often, saves the file with the date in the name, and believes that's already version control. Why it happens: the hand-dated copy resembles versioning closely enough to give a false sense of security; you do effectively have copies. How to spot it: ask yourself if, with your current method, you can answer in ten seconds "what exactly changed between Tuesday's version and today's, and who changed it and why?" If the answer is "I'd have to open both files and compare them by eye," you're not versioning, you're accumulating copies. How to fix it: that's exactly what the module solves. Module 1 already showed why export/import has limits; here we lay the tool that covers them on top.

Exercises

Exercise 1 — Diagnose your current method. Think about how you currently save versions of your workflows (or of any important file: a document, a spreadsheet). Write down, honestly, how you'd answer these four questions with your current method: (a) which was the version that worked exactly a week ago?, (b) what changed between that version and the current one?, (c) who made that change and why?, (d) if you needed to go back to the one from a week ago, how long would it take and how sure would you be that you grabbed the right one?

See solution

There's no single answer; the value is in your own answer. The pattern almost everyone finds when doing this exercise honestly is that all four questions get answered with some version of "I'm not sure" or "I'd have to go look and compare by hand." That's not a flaw of yours: it's the real limitation of the dated-copies method, which feels solid until you interrogate it.

Save your four answers. When you finish the module, come back to them: with Git, all four get answered with a command and with certainty. (a) gets answered by git log; (b) by git diff; (c) by the author and message of each commit; (d) by a git revert or a git checkout, thirty seconds. Seeing the "before" written in your own hand makes the "after" feel like what it is: a concrete improvement, not a technical fad.

Exercise 2 — Translate the market's promise. The phrase we quoted, "as version-controlled, documented JSON," has three parts. Explain in your own words what each one requires and in which module or lesson of this guide it's taught: (a) "version-controlled," (b) "documented," (c) "JSON."

See solution

(a) "Version-controlled": that the workflow have a real history —who changed what, when, and why— and that you can move through that history. That's, literally, this entire Module 2.

(b) "Documented": that alongside the workflow there be a readable explanation of what it does, how it's used, and what it needs to run —usually a README file. That comes later, in Module 3, when we structure the repository for handoff. The commit messages you learn in lesson 3 are already a first form of documentation: every change is explained.

(c) "JSON": that the unit you deliver is the workflow exported in its text format, not a screenshot or a description. Exporting to JSON you saw in Module 1; normalizing it so it's clean and diffable is Module 3.

Why it works: the exercise connects a real job posting phrase to the concrete curriculum. When an interview asks you if you know how to deliver "version-controlled, documented JSON," you'll be able to answer not with a vague "yes," but describing exactly what you did for each word.

Exercise 3 — Anticipate the thread. Without looking back at the module thread table, write from memory what happens to the order-triage workflow in each of the seven lessons that follow (2 through 8), one sentence each. Then compare against the table and mark the ones you missed.

See solution

(2) You install Git and turn the project folder into a repository. (3) You make your first commit —the first photo— and learn to make clean ones. (4) You change the workflow and learn to read the diff showing what changed. (5) You try out a new idea on a separate branch, without touching the good version. (6) You push the history to GitHub to back it up and share it. (7) You revert a change that broke the workflow and go back to the version that worked. (8) You put it all together into the deliverable project.

Why it works: if you rebuilt at least five of the seven, you've already internalized that the module isn't eight separate Git topics, but the life of a change in a workflow —save, compare, experiment, share, revert. The ones that most often slip away tend to be 4 (diffs) and 7 (rollback), which are the ones that don't yet have a concrete image in your head. After their lessons, they won't slip away anymore.

Summary and next step

In this lesson you saw why the natural way of versioning —copies with the date in the name— fails exactly when you need it most: it doesn't say what changed, or who, or why, it doesn't let you experiment without risk, and it turns "going back" into opening old files and guessing. You saw why Git is the right tool and not Dropbox, Google Drive, or n8n's internal history: Git was designed to keep the history of text files —and an exported workflow is text— in a way that lets you compare, group changes with intent, work in parallel, and go back to any point with precision. You separated two names people mix up all the time: Git is the local program; GitHub is an optional site for hosting a copy. And you received the module's thread: Cumbre's order-triage, which you're going to put under version control step by step all the way to a shared remote.

Before moving on to lesson 2 you should be able to: explain in one sentence why dated copies aren't version control; state the difference between Git and GitHub; and name at least four of the seven lessons that follow, with what happens to order-triage in each.

What you haven't done yet is the most important part: actually touching Git. So far we've only looked at the map. Lesson 2 gets down to the ground: you're going to install Git on your machine —with the specific path for your operating system— configure it with your name so your commits carry an author, and run your first git init on the cumbre-automations folder, seeing with your own eyes how an ordinary folder turns into a repository. No abstract theory: one command, one response in the terminal, and an explanation of what just happened.

Resources

• What is Git? — Git Docs — the first chapter of the official Git book, free and online. Explains where Git comes from and why it keeps history the way it does. Dense but authoritative.
• About Version Control — Git Docs — the conceptual introduction to version control, useful for reinforcing why hand-made copies fall short.
• Source control (Git) — n8n Docs — n8n's official page on version control and environments. Describes what the platform brings natively; useful for keeping in mind the Community/Enterprise boundary that Module 6 discusses in depth.
• Export and import workflows — n8n Docs — how a workflow gets exported to JSON, the file we're about to version. A Module 1 refresher in case you need it before lesson 2.