5.3 KiB
| title | description |
|---|---|
| Understand source control in n8n | Understand the concepts behind source control in n8n. |
Understand source control in n8n
!!! note "New to Git and version control?" If you're new to Git, don't panic. You don't need to learn Git to use n8n. This document explains the concepts you need. However, you do need some Git knowledge to set up the environments, and to copy work between environments, as this happens in your Git provider.
!!! note "Familiar with Git and version control?" If you're familiar with Git, don't rely on behaviors matching exactly. In particular, be aware that version control in n8n doesn't support a pull request-style review and merge process (unless you do this outside n8n in your Git provider). Read the Environments in n8n section to understand how n8n uses Git to support environments.
Source control patterns
The relationship between n8n instances and Git branches is flexible. You can create different setups depending on your needs.
[TODO: more decision making help]
Multiple instances, multiple branches
This pattern involves having multiple n8n instances, each one linked to its own branch.
This is the setup to use if you want different n8n instances for testing and production.
[TODO: note that this is one possible multi-env setup, and main advantage is PR and safety]
Multiple instances, one branch
Use this pattern if you want the same workflows, tags, and variables everywhere, but want to use them in different n8n instances.
[TODO: note this can also be used for test/prod type setups, but NOTE RISK]
This is useful when testing a new version of n8n: you can create a new n8n instance with the new version, connect it to the Git branch and test it, while your production instance remains on the older version until you're confident it's safe to upgrade.
One instance, multiple branches
The instance owner can change which Git branch connects to the instance. The full setup in this case is likely to be a Multiple instances, multiple branches pattern, but with one instance switching between branches.
This is useful to review work. For example, different users could work on their own instance and push to their own branch. The reviewer could work in a review instance, and switch between branches to load work from different users. In this case,
One instance, one branch
This is the simplest pattern.
Git: Key terms and concepts
This section provides the concepts and terminology needed to save work to Git from n8n, and fetch changes from Git into n8n. It doesn't cover everything you need to set up and manage a repository. The person doing the Setup should have some familiarity with Git and with their Git hosting provider.
!!! note "This is a very brief introduction" Git is a complex topic. This section provides a very brief introduction to the key terms you need when using environments in n8n. If you want to learn about Git in depth, refer to GitHub | Git and GitHub learning resources{:target=_blank .external-link}.
What is Git?
Git{:target=_blank .external-link} is a tool for managing, tracking, and collaborating on multiple versions of documents. It's the basis for widely used platforms such as GitHub{:target=_blank .external-link} and GitLab{:target=_blank .external-link}.
Branches: multiple copies of a project
Git uses branches to maintain multiple copies of a document alongside each other. Every branch has its own version. A common pattern is to have a main branch, and then everyone who wants to contribute to the project works on their own branch (copy). When their work is finished, their branch is merged back into the main branch.
Local and remote: Moving work between your machine and a Git provider
A common pattern when using Git is to install Git on your own computer, and use a Git provider such as GitHub to work with Git in the cloud. In effect, you have a Git repository (project) on GitHub, and work with copies of it on your local machine.
n8n uses this pattern for version control and environments: you'll work with your workflows on your n8n instance, but send them to your Git provider to store them, and copy them between environments.
n8n uses a two [TODO: or three?] key Git processes:
- Push: send work from your instance to Git. This saves a copy of your workflows, tags, and variables, to Git. You can choose which of these you want to save.
- Pull: get the workflows, tags, and variables from Git and load it into n8n. !!! warning "Pulling overwrites your work" If you have made changes to a workflow in n8n, you must push the changes to Git before pulling. When you pull, it overwrites any changes you've made if they aren't stored in Git.
- Commit: a commit in n8n is a single occurrence of pushing work to Git. [TODO: hopefully we can remove commit language but add this to above list if needed]