Skip to main content

Source Control best practices

Recommendations for structuring branches, instances, and deployments with Source Control.

You can manage changes to Retool apps, classic apps, workflows, queries, resources, and themes under source control management (SCM) providers, such as GitHub, GitLab, AWS CodeCommit, Bitbucket, and Azure Repos. The following best practices cover how to structure instances and branches, how to keep merges predictable, and how to deploy.

Develop on staging​

Start app development on an instance representing staging or development, and promote to production through multi-instance releases instead of building directly in production. Leave experimental work unprotected until it's worth the review cycle.

An app can be created and protected from any instance connected to the remote repository, so build there when the resources require connection to a production instance, but treat that as an exception.

Follow merge conflict prevention strategies​

The development processes you use can help prevent merge conflicts from arising in the first place.

Keep branches short-lived​

Keep a branch open for a week or less, and merge as soon as review completes. The longer a branch stays open, the more changes land on main behind it, and the more likely a conflict becomes.

Add test deployments to your CI pipeline​

A test deployment validates a change against your Retool instance before it merges. Adding it as a required check in GitHub or your SCM provider stops invalid changes from reaching main.

Divide work so builders don't collide​

Two builders editing the same app on separate branches will conflict. Two builders editing different parts of it usually won't.

  • Use modules to encapsulate work. A module is an isolated part of an app that one person can develop without affecting others. Before starting a complex app, plan which pieces should be modules.
  • Split responsibilities by file area. Assigning one builder the executable pieces such as queries and transformers and another the visual pieces such as headers, titles, and images keeps them in different directories, since the former affects lib/ and the latter mostly src/.

Understand how releases work with source control​

Releases are exclusive to the instance in which they're created. Creating and publishing a release isn't captured in source control, so a release published on staging doesn't exist on production.

Treat releases as a per-instance deploy mechanism layered on top of Source Control. If you need the same release version across instances, use multi-instance releases.

Watch for deployments that stop​

The Deployment Dashboard shows the commit SHA that is deployed, the Source Control configuration, and the deployment logs. Check it after any change that should have deployed.

This helps catch deployments that silently stop, because apps keep working on the last successfully deployed commit.

Restrict who can configure Source Control​

Configuring Source Control requires admin access, and the configuration includes credentials for your SCM provider. Keep the set of administrators who can edit it small, and rotate the access token on the same schedule as your other service credentials.