Recommended workflow for Source Control

First, follow our getting started setup instructions to create and protect an app. Once protected, this app will be created in all instances connected to the retool_source repository, and changes can only be made through pull requests on your remote source control management provider (GitHub, GitLab, etc.).

Next, open a branch. You can now commit & push changes to your app at meaningful checkpoints without the worry of overwriting developers or rolling back a complex change. If you need, you can always go back in your history to restore or undo changes.

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!

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.


We recommend starting app development in an instance representing a staging or development environment; however, an app can be created and protected from any instance of Retool connected to the remote repository (named retool_source in the diagram). This is useful if you have a particular resource that's only accessible from your production environment.

We also recommend using one branch instead of a "Git Flow” branching model. Since you have the fine-grain control to release each protected app independently at the cadence of your choosing, we recommend using a single, protected main branch that each instance points to.

If batching changes across multiple apps is a requirement, we recommend manually coordinating releases to synchronize updates after apps have the latest versions have synced down. If that is insufficient, you could also point your instances to other integration-like branches such as staging and production and manually cherry-pick and merge to batch and promote changes.



Releases are exclusive to the Retool instance in which they were created. Creating and publishing releases for an app are not captured in source control, and can be treated as a deploy mechanism. Learn more about Release Management.

What’s Next