Version Control with Git for Workflows

Hello! Welcome to the next lesson in our module on Production Operations and Scaling.

In our last session, we established a comprehensive backup strategy, covering both full system recovery and application-level backups. We touched on the idea of exporting workflows as JSON files, which is perfect for versioning. Today, we'll expand on that concept to fully address our learning outcome: Track workflow versions using a Git-based workflow (export/import and commit).

Given your background as a software developer, today's topic will leverage concepts you're already very familiar with: treating infrastructure as code. We will apply the principles of Git version control—branching, committing, and reviewing changes—to manage your n8n workflows. This practice is fundamental for building stable, maintainable, and collaborative automation projects.

We'll explore a few different ways to achieve this, from a manual developer-centric approach to more automated methods.

The Rationale: Why Use Git for n8n Workflows?

Before we dive into the "how," let's briefly recap the "why." While n8n is a low-code platform, complex workflows are essentially software. Storing them in Git provides several key advantages:

• Change History: See who changed what, when, and why.
• Safe Collaboration: Use feature branches to develop new automations or fix existing ones without impacting the production version.
• Code Review: Use pull requests (PRs) to have teammates review changes before they are merged and deployed.
• Rollbacks: Easily revert to a previously known good version if a new change introduces a bug.
• Disaster Recovery: A Git repository serves as a robust, off-site backup of your workflow logic.

1. The Developer's Method: Manual Export and Commit

This is the most flexible and powerful approach, mirroring a standard software development lifecycle. It involves manually exporting your workflow's JSON representation and committing it to a Git repository.

The article from Evalics provides an excellent blueprint for this entire process.

Let's break down the key steps from the article into a practical workflow.

Step 1: Set Up Your Git Repository

As recommended, a well-organized repository is key. A good structure looks like this:

n8n-automations/
├── workflows/
│   ├── sales/
│   ├── marketing/
│   └── operations/
├── .gitignore
└── README.md

Your .gitignore file is critical for security. It ensures you never accidentally commit sensitive information. At a minimum, it should include:

# Never commit actual secrets
credentials.json
.env

Note: As we learned in the previous lesson, you can export credential stubs for reference, but the actual secret values should never be in your repository.

Step 2: The Development Cycle

This is where the process aligns with standard Git practices.

1. Create a Branch: Before making changes, create a new feature branch:
   git checkout -b feature/update-customer-onboarding

2. Develop in n8n: Make your changes to the workflow in the n8n UI as usual. Test it using the execution panel.

3. Export the Workflow: Once you're satisfied, export the workflow. You can do this from the n8n UI (three-dot menu -> Download) or via the CLI for more control (as we saw in the last lesson). Save the resulting JSON file in the appropriate folder in your repository, overwriting the old version if it exists.

4. Commit Your Changes: Commit the change with a clear, descriptive message. Using the conventions from the article is a great practice.

   git add workflows/operations/customer-onboarding.json
   git commit -m "[Update] Add validation step for customer email in onboarding workflow"
   git push origin feature/update-customer-onboarding
   

5. Create a Pull Request: On GitHub (or your Git provider of choice), create a pull request. This is where the magic happens. You can review the JSON diff to see exactly what changed—a powerful tool for catching errors before they go live.

Step 3: Restoring or Deploying a Version

To restore a previous version or deploy a workflow to a new n8n instance, the process is simple:

1. Find the workflow's JSON file in your Git repository (from the correct branch or commit).
2. Copy the entire JSON content.
3. In n8n, create a new blank workflow and simply paste the JSON onto the canvas. n8n will automatically recreate the entire workflow.

2. The Automated Method: Workflow-based Backup

For a more "hands-off" approach, you can create an n8n workflow that automatically backs up all your other workflows to GitHub. This is less of a development lifecycle and more of an automated backup and versioning system.

This method is clever and uses n8n to manage itself. Here’s the high-level logic:

• Trigger: A Schedule node runs the workflow daily or weekly.
• List Workflows: The n8n API node is used to get a list of all workflows on your instance.
• Process and Commit: The workflow loops through each item, converts the workflow JSON to a file, and uses the GitHub node to commit the file to your repository. The logic can even check if the file already exists and update it.

When to use which method?

Test your understanding!

You are working on a critical new workflow that integrates a payment processor. You need a colleague to review your logic before it goes live. Which of the two Git-based methods we've discussed is better suited for this task, and why?

Show answer

The Manual Export and Commit method is far better suited. It allows you to work on a dedicated feature branch without affecting the main branch. When you are ready for a review, you can create a Pull Request. Your colleague can then see the exact diff of your changes in the workflow's JSON file and leave comments, ensuring a proper code review process before the changes are approved and merged. The automated method would just commit the work-in-progress without this formal review gate.

3. A Note on n8n's Internal Versioning

It's also important to know that n8n has its own versioning capabilities, which are excellent complements to a Git-based strategy.

Built-in Version History

Since n8n version 1.0+, the platform distinguishes between Saving and Publishing.

• Save: Takes a snapshot of your current workflow without activating it. You can do this many times.
• Publish: Takes a snapshot and activates the workflow (or the production URL of a trigger).

This creates a version history directly within the n8n UI, allowing you to quickly revert to a previous state. This is perfect for recovering from a minor mistake during development without needing to go through the full Git cycle. The video below explains this feature well.

Native Git Integration (Enterprise)

For completeness, you should be aware that n8n's Enterprise plan offers native Git integration. This allows you to link an n8n instance directly to a Git repository branch and use push and pull buttons within the UI. It's designed for managing complex development, staging, and production environments. While not available on the standard self-hosted version, knowing it exists is part of achieving "full stack" mastery. You can read more in the official documentation.

Conclusion

You now have a complete toolkit for versioning your n8n workflows like a professional software developer.

Key Takeaways:

• Treating your workflow JSON as code and storing it in Git is a best practice for stability, collaboration, and auditing.
• The manual Git workflow (branch, develop, export, commit, PR) offers the most control and is ideal for team collaboration and formal review processes.
• The automated workflow-based backup is an excellent "set and forget" solution for ensuring you always have a recent version of all your workflows in a Git repository.
• n8n's internal versioning is a complementary tool, perfect for quick snapshots and rollbacks during active development.

A robust strategy often combines these: use the manual Git workflow as your "source of truth" for deployments and use n8n's Save button frequently during development as a local undo/redo mechanism.

Preview of the Next Lesson:

Now that we are committing our workflow code to a repository, it is more critical than ever to ensure we aren't accidentally exposing secrets. Our next lesson, Configure credentials securely in a production environment (e.g., via environment variables), will tackle this head-on, ensuring your automation infrastructure is not only version-controlled but also secure.