Skip to main content

Manage Source Control branches

Learn how to view, edit, delete, and switch Source Control branches.

On Retool Cloud and self-hosted Retool versions 3.6.0 and later, you can:

  • Edit multiple apps, modules, and queries on the same branch.
  • Commit changes directly in the editor.
  • Switch between branches and apps using the Branch menu.

On earlier Retool versions, a branch only tracks a single app or module.

Edit apps, modules, and queries​

With multi-element branching, you can edit apps, modules, and Query Library queries on a single branch. Each commit contain changes for a single app, module, or query, but branches can contain commits across apps, modules, and queries. This allows you to combine your dependent changes into a single pull request, instead of creating and merging pull requests for each dependent module or query.

Branches must all be created from main.

Branch menu​

From the branch menu in the bottom left status bar, you can:

  • View your commit log.
  • Switch branches.
  • Edit other apps and modules on the same branch.
  • Create a pull request.
  • Rename, reset, and delete your branch.

Build apps on and off branches​

When you open a new tab, you are always on the main branch.

When you create a new app or module while you're on a local branch, you can create it on or off your branch.

When you select Create on current branch, the app or module is created locally on your branch and considered In development. Apps and modules in development are only visible to their creators on the local branch until they are merged into source control repositories. After you merge an In development app or module to your source control repository, it is visible to the rest of your organization. In development apps and modules are useful when you want to privately develop and iterate on apps before you share them widely.

When Create on current branch is not selected, the new app or module is not protected.

Rebase branches​

Rebasing allows you to integrate changes from one branch to another. It's often used to update a development or feature branch with the latest changes from a more stable branch (e.g.,main).

If you need to update your Source Control branch, you can perform a rebase on a branch that you own using the following steps.

  1. Ensure all changes are committed on the branch.
  2. Rebase the branch within your SCM provider and resolve any merge conflicts.
  3. In Retool's app editor, open the branch menu in the lower left and select ••• > Reset branch to update the branch.

Source Control branches can only be rebased by the branch owner.

Automatically delete branches​

Retool automatically deletes branches after changes are merged, when the remote branch no longer exists, and there are no uncommitted changes on the branch.

Otherwise, users can delete branches that they own directly from the branch menu in the app.

Multi-instance​

To preview a branch of an app pushed from another instance, create a new branch in your current instance, and select Reset branch in the status bar. Select the relevant branches in the modal to pull in the origin branch changes.

Reset branch modal

Do not manually add any Toolscript (*.tsx), YAML, JSON, or query (*.sql, *.js*) files to the Source Control repository. All changes to apps, workflows, queries, and resources must be done through the Retool interface. Manually adding these files can cause deploy failures.

Any other files (e.g., README.md) are skipped during deploys can be safely added to the repository.