Skip to main content

Multi-Branch Mode

Enterprise Plan

Branching lets several builders work on the same applications at the same time without overwriting each other. Each builder works on their own branch, where changes stay separate from what is live until they are reviewed and merged through a pull request in your Git provider.

Use Cases​

  • Building features in parallel. Two builders can change the same application at the same time, each on their own branch, without overwriting each other's work.
  • Reviewing changes before they reach production. The default branch is read-only, so nothing becomes releasable until a reviewer has approved the pull request that brings it in.
  • Fixing an earlier version without disturbing what is live. Create a branch that starts from that saved version, correct it, and save the fix without moving the head of the default branch. Refer to Version Control with Git.
  • Showing who approved a change. Every change arrives through a merged pull request, so the repository records the author, the reviewer, and the approval alongside the diff.

What a Branch Contains​

A branch in ToolJet is not tied to a single application. Each branch holds its own copy of every application, module, datasource, and folder, so switching branches changes what you see across all of them at once.

All branches live inside the same workspace. You do not need a separate workspace for each branch, for each builder, or for each feature. Everyone works in one workspace and switches between branches in it.

There are two kinds of branches:

  • Default branch: The branch configured in your GitSync connection, typically main or master. It holds the live version of your applications. When branching is enabled, this branch is read-only and changes can only enter it through a merged pull request.
  • Feature branches: Independent copies created from the default branch, where you make changes freely. Each feature branch is isolated until its changes are merged back.

Single-Branch and Multi-Branch Mode​

GitSync starts in single-branch mode. Multiple branches are opted into per workspace. See Enable Branching for how to turn them on.

BehaviorSingle-branch modeMulti-branch mode
Feature branchesNot availableCreated from the default branch
Default branchEditableRead-only
Changes reach the default branch byCommitting directlyMerging a pull request

When branching is enabled and you are on the default branch, ToolJet blocks these actions:

  • Creating or editing applications and modules
  • Creating or deleting datasources
  • Creating applications from templates
  • Using any AI features
Applications page on the locked default branch, with a banner stating that a branch is needed to add or edit apps

How Changes Reach the Default Branch​

Branching splits the work between two systems. You build and commit in ToolJet, and the review and merge happen entirely in your Git provider. ToolJet cannot merge branches.

Refer to Pull Requests for the full flow, including how to open and track pull requests from ToolJet.

Resources Covered by a Branch​

Applications, modules, datasources and their folder assignments are branch-scoped. On a feature branch, changes to a module or datasource stay on that branch and reach the rest of the workspace only once they are committed and merged. In single-branch mode there is nothing to isolate them from, so those changes apply across the workspace immediately.

Workflows and ToolJet Database tables are not branch-scoped yet. They behave the same on every branch.

Folders​

Your folder structure in ToolJet is written to Git as the directory structure of the repository, so an application inside a Billing folder is committed to a Billing/ directory.

Folders are also workspace-level rather than branch-scoped, so a folder created on one branch exists on all of them. Between those two constraints, multi-branch mode restricts folders everywhere, not just on the default branch:

ActionSingle-branch modeMulti-branch mode
Rename a folderAllowedBlocked
Delete an empty folderAllowedAllowed
Delete a folder containing resourcesBlockedBlocked, and the error names the branches still using it

Where Branch Controls Appear​

The branch dropdown and the Pull button appear in the header on the Applications, Data sources, and Modules pages. The header Commit button appears only on the Data sources page. Applications and modules are committed from inside the App Builder, see Push and Pull Commit.

Using GitSync Across Multiple Instances​

If you run separate ToolJet instances for different environments, you can connect them to the same Git repository. Git acts as the bridge between instances.

  • Development instance: Builders create branches, make changes, commit, and merge pull requests. Saved versions are tagged in Git.
  • Staging or production instance: Pull saved versions from Git to deploy and release them. No manual export or import is needed.

This enforces environment separation at the infrastructure level while keeping all instances in sync through a single repository.

info

To decide whether a single or multi-instance setup suits your organization, see Choosing Your Instance Setup.

Limitations​

  • Branching works with GitHub and GitLab.
  • Branches are always cut from the default branch, never from another feature branch. You can still choose which point in the default branch's history to start at.
  • Pull requests must be created and merged in your Git provider. ToolJet cannot merge branches.
  • Branches cannot be renamed once created.
  • Merge conflicts must be resolved in Git before merging.
  • Workflows are not branch-scoped.
  • Only one draft version is allowed per application per branch.

Need Help?​