Skip to main content

Source Control recommended workflow

Learn about the recommended workflow to use with Source Control.

Available on:Enterprise plan

Use Source Control to:

  • Collaborate with other users on the same apps
  • Prevent users from directly editing mission-critical apps
  • Review code in Toolscript
  • Sync changes across multiple instances

Protect an app

First, create and protect an app and any of its dependent modules, queries, or resources.

Once protected, this app is created in all instances connected to the retool_source repository. Changes can only be made through pull requests on your remote source control management provider (GitHub, GitLab, etc.).

Create a branch

Next, open a branch with an intuitive name and start developing. You can always go back in your history to restore or undo changes.

If you're working on an app with multiple dependencies (modules, library queries, or resources), you can continue your work on the same branch with multi-element branching.

You can also select Make collaborative when you create the branch to allow other users to push changes to it.

Commit and merge changes

You can now commit and push changes to your app at meaningful checkpoints without the risk of overwriting other builders or rolling back a complex change.

Once you are happy with the new functionality in your branch, you can open a pull request and get a review from fellow developers on your team. Once approved, merge the pull request into your default branch (typically main). Within seconds, the default or main branch within Retool will reflect these changes and your end users will be able to see them!

Revert changes

If you need to roll back a complex change, you can revert the commit from your source control provider. Retool picks up any changes made to the default branch.

If you would rather test reverting your changes on a branch, you can reset your local branch to any remote branch from the branch menu.


For mission-critical apps, you can also pin a release for end users. This allows you to preview or test changes before releasing them to end users. Using the Releases feature allows you to deploy apps at the cadence of your choosing, which gives you the ability to batch changes and/or manually test for regressions.

Releases can be accessed by clicking on the version number in the header in Preview mode of the configured default branch (typically main). For more information, explore our Release Management options.

Remote repository guidelines

Retool recommends you do not manually add any Toolscript (*.tsx), YAML, JSON or query (*.sql, *.js*) files to your Retool directories. Manually added Toolscript or YAML files can be interpreted as Retool changes and break deploys.

Any other files (, *.js) are skipped during deploys and are safe to add to the repository.