Skip to main content

Source Control

Source Control in Retool allows you to manage changes to Retool content (apps, workflows, queries and resources) using source control management (SCM) providers. Retool currently supports GitHub, Gitlab, Bitbucket, AWS CodeCommit and Azure Repos. This document is not focussed on configuring Source Control in Retool, you can learn more about that in the official documentation here. On this page we will compare the various Git workflows that are supported by Retool and how these are being used by our largest customers.

Retool concepts​

Before we dive into the various Git workflows, let's first look at some of the Retool concepts that are important to understand.

Multi element branching​

Resource: https://docs.retool.com/source-control/guides/manage-branches#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.

Toolscript​

Resource: https://docs.retool.com/source-control/concepts/toolscript

Toolscript is a JSX-style markup language built to serialize Retool apps protected using Source Control. Unlike its YAML predecessor, Toolscript is designed to be human reviewable.

VERSION_CONTROL_LOCKED​

Resource: https://docs.retool.com/reference/environment-variables#version_control_locked

When this environment variable is set to true, Retool will prevent users from making changes to apps, modules, and queries that are protected using Source Control. This is useful when you want to prevent users from making changes to apps, modules, and queries that are protected using Source Control. We recommend using this environment variable on your production instance of Retool.

Git workflows​

A Git workflow is a set of guidelines and practices that help teams collaborate effectively when using version control. They can be as simple or complex as your team needs. Given the flexibility that git offers there is no one-size-fits-all Git workflow. At this point it is important to highlight that picking a workflow needs to be something that works for your team and your organization. In this section we will look at the various Git workflows that are supported by Retool and we provide tips on how to implement them. A few questions you can ask yourself before implementation are the following:

  1. How many Retool instances do you have?
  2. What git workflows are you familiar with?
  3. Does the workflow scale with your team and organization?

1. Feature branch workflow​

This is the most common Git workflow. In this workflow, each new feature is developed in a dedicated branch. This branch is created off the main branch and merged back into the main branch when the feature is complete. This workflow is supported by Retool and is the default workflow when you enable Source Control in Retool.

In a single instance setup you configure a single Git repository in Retool. This repository will contain all your Retool apps, modules, queries and resources. When you create an new application and you are ready to add it to Source Control you have to protect it. By protecting the application every future change will have to be made through a feature branch. Once you have finished making changes to an app in your feature branch, you will have to open a PR and merge it into the main branch. Retool will automatically pick up the changes on the main branch in your remote repository.

For multi-instance setups you follow the same process as for a single instance setup. Each instance points to the same Git repository. If you are using a development and production instance, then both will get the latest changes from the main branch.

Releases​

The best way to control what changes are being displayed to end users of your applications is by using releases. By default, every edit you make to a Retool application that is not protected by Source Control are automatically saved to the current working version. This version is live to all users. When you are using Source Control you can control what version is live to your users by creating a release. Retool uses Semantic Versioning to version your applications. When you create a release you can specify the version number. For example, you can create a release with version 1.0.0 and deploy that to your production instance. When you are ready to deploy a new version of your application you can create a new release with version 1.0.1 and deploy that to your production instance. This way you can control what version of your application is live to your users. You can learn how to create releases here. When you use Source Control you pin your releases to specific commits. That way you can push changes from feature branches on your development instance to your remote main branch, but the application in the production instance will not be updated until you create a release and deploy that release.

Single branch flow with releases

2. Instance branches & git cherry-pick​

From a Retool perspective this workflow is similar to the feature branch workflow. However, the remote repository is setup and connected differently to each Retool instance. Imagine the following scenario:

  • You have a development and production instance of Retool. Your development instance is used by your developers to build and test new applications. Your production instance is used by your end users.
  • You have a single Git repository that contains all your Retool apps, modules, queries and resources.

Rather than having one main branch, you create a branch for each instance of Retool. In this scenario, however, you would have a dev and main / prod branch. You configure your development instance to point to the dev branch and your production instance to point to the prod branch. When you are ready to deploy changes from your development instance to your production instance you create a pull request. This PR will be merged into the remote dev branch. In this scenario, the production instance will not automatically pick up any changes or edits. Instead, you will have to manually merge the changes from the dev branch into the prod branch. This can be done using the git cherry-pick command. You can learn more about this command here.

The reason for using this particular git flow is to have more control over what changes are being deployed to your production instance. You can use the dev branch to test new features and changes before merging them into the prod branch. This workflow is supported by Retool, but it is not the default workflow.

With this flow, we recommend having a select group of developers who are responsible for merging changes from the dev branch into the prod branch via cherry-picking. This way, you can ensure that only tested and approved changes are being deployed to your production instance. Cherry-picking commits happen outside of Retool and are done using the command line or SCM software. This is a manual process and can be error-prone. We recommend having a clear process in place and documenting the steps needed to merge changes from the dev branch into the prod branch.

Cherry pick flow