Skip to main content

Source Control Best Practices

Overview​

Retool Platform provides source code management (SCM) integration when using an Enterprise license. SCM integration supports several Git-based providers and focuses on tracking apps, workflows, queries, resources, and themes. This document will cover the best practices employed by Retool Professional Services / Partners to consistently manage development and releases to the Retool platform. For more information on Source Control setup please refer here.

Retool Artifacts​

Retool development focuses on creating Apps, Workflows, Queries, Resources, and more. When developing within the Retool platform, an artifact, JSON or Toolscript represents the developed core elements.

Branching Strategy​

When employing Git-based solutions for source code management, it is essential to identify the branching strategy builders and operators use. A branching strategy identifies how a development team has agreed to collaborate when employing a Git repository. This can include branch identification, naming convention, branch-to-environment alignment, and more.

Feature Branching Strategy (low-complexity)​

Retool 3.114-stable release (Q4) introduces support for feature branching across Retool Apps, Modules, Resources, Workflows, and the Query Library. The feature branching strategy comprises a main branch and individual/unique/temporary feature branches that capture new work by the branch owner. When new work is completed, the owner defines a pull request to merge the Git commits in a feature branch with the main branch. The following image demonstrates this in action; more details are available here.

Feature branching strategy diagram

Software Development Lifecycle Example​

Once developers have implemented application changes, it is essential to understand what Retool provides to deploy the change and Retool's recommendations for environments when using Retool Self-hosted and Retool Cloud. A separate document discussing these features is found here. Using this, the following examples discuss a feature branch and gitflow deployment.

Initialize Git Repository with Application​

Before teams develop features against a repository, the first step is initializing the repository with the application.

NOTE: This assumes the administrator has configured the Git repository per the instructions provided here.

The lead developer would initialize the repository through the following steps:

  • The lead developer identifies the application/workflow to protect.
  • Within the application, select … > Protect app. A dialog will appear, choose Protect application.
  • The previous step will create a branch in GitHub with the initial commit. Select Open pull request to start merging this branch to main.
  • GitHub will appear, allowing the lead developer to view the initial commit and pull request details. Select Create pull request.
  • Once the pull request has been created, the lead developer and team can review it, approve it and perform the merge. Select Merge pull request.
  • To complete the process, select Confirm merge.
  • Once the repository Pull Request has been merged, Retool will display a dialog indicating that protection is complete. Select Done.
  • The application will now appear with a Protected icon, indicating it is under Source Control.
  • Hovering over the app displays an Edit selection that exposes Git information, including the ability to Create new branch and View all branches… This is demonstrated in the next section.

Feature branch development​

The following provides an example of the feature branching workflow for an existing app.

  • A developer has a new feature encompassing an App.
  • Developer logins to Retool Development Instance (dev.user_domain.com)
  • The developer selects the Protected App, selects Create New Branch, and updates the App and associated Query. When ready, the developer commits the multi-element change and creates a Pull Request, pushing the change to the GitHub repository.
  • The team performs a Pull Request review of the App/Query change by examining the ToolScript zip contents.
  • The team approves the PR that merges this commit to the main branch.

Feature branch deployment​

When configuring Retool SCM the admin identifies the branch that Retool monitors for deployment. In feature branch deployment, the last commit on the main branch is what is deployed.

  • Within Retool, the administrator is able to access Settings > Source Control > Deployment Dashboard to see the latest and prior commits. Each target commit is identified by a unique id, Simple Hashing Algorithm (SHA).
  • Selecting Logs, allows an admin to get further detail from Retool’s DeployBot for debugging purposes. It provides deployment details and aligns the deploy to the previous SHA and target SHA. Both of which are viewable by clicking the respective Target commit links.

Feature branch deployment with Release on single instance​

NOTE: This feature works on a single instance of Retool.

As was shown in Feature branch deployment, the latest commit on the configured branch (e.g., main) is what is deployed. In order to control the specific commit that is published and viewable by end users, Retool SCM can be combined with Retool Releases. Retool Releases saves the current state of an App allowing an admin to control which commit is made live versus only using the latest commit.

  • When a commit is merged into the main branch, the admin can switch to the main branch in Retool and then select Release > Create new > Releases and History. Here they can specify a description and version to associate with the latest commit. This process is repeated for each commit allowing unique versions to be defined and deployable within Retool.
  • Once the release exists, the admin can select which is live by selecting … > Publish release.

Appendix: Gitflow Branching Strategy​

Gitflow Branching Strategy (high-complexity)​

NOTE: Customers requiring Gitflow should work closely with Retool Professional Services

The previous sections outlined the Feature-branching strategy as the most efficient mechanism for Retool development. Some enterprise organizations mandate the use of Gitflow, an alternative branching strategy. In Gitflow, several branches are employed for development, features, production, releases, and hotfixes, as described here with the purpose of aligning the develop and release branches for lower-level environments (e.g., Dev, Test) and the main branch with production. For this discussion, we will omit the release branch to illustrate the use of Git cherry-pick. Git cherry-pick allows an admin to pick specific commits on the develop branch in this example and apply them to the main branch, thus publishing only specific functionality when desired.

The following image, used for demonstration purposes, shows the main branch, a develop branch, and a feature branch. Developers will create feature branches off of the develop branch and when complete will perform a Pull Request into the develop branch. After testing/validation has been performed in develop, the admin selects a commit on the develop branch, uses cherry-pick, and updates the main branch.

Gitflow branching strategy diagram

Gitflow with Cherry pick​

For customers employing Gitflow, the following video demonstrates the following:

  • Create a feature branch from develop.
  • Delete a component and commit to feature branch.
  • Create a Pull Request to merge commit to develop branch.
  • Switch to main branch and use cherry-pick to select commit from develop branch and add commit to main branch.