Configuring Source Control in Retool

This laboratory focuses on configuring Retool with Github, a Source Control Management (SCM) provider. Additional documentation is provided here. This lab will demonstrate the use of an existing Space but can be configured without a Space as well.

Requirements

To configure Source Control you will need:

Retool Enterprise Cloud or Self-hosted
GitHub or GitHub Enterprise account instructions here

Steps

Create Github App

The GitHub App provides an API based mechanism that Retool uses to integrate Github functionality for managing changes in Retool Apps, Modules, Library Queries,and Workflows. Refer to the following documentation to configure / setup a GitHub App.

Create GitHub Repo

For this laboratory a single app, developed by a single team will be stored in the repository called retoolApp1.

To create a repository login to your GitHub account and select New. The following form requires completion to define an initial empty repository:

SCM1

Select the owner, repository name, description, select Add a README file, specify Add .gitignore and license if applicable. The following is an example of the form completed.

SCM2

Select Create repository.

Add GitHub Repo to GitHub App

Once the repository is created, it needs to be added to the previously created GitHub App so it is accessible to Retool.

In GitHub select Settings > Applications > Installed GitHub Apps > (your GitHub App) > Configure

SCM22

Repository Access is exposed and the respository can be selected via Select repositories as seen in the following figure.

SCM22

Select Save once the repository is added. This will allow Retool to then access the specified repositories via the GitHub App.

Configure Retool Source Control in a Space

Retool recommends as the administrator or space administrator, defining source control on a space by space basis. This allows teams to manage their development independently of one another.

Log in to Retool as the administrator / space administrator and select a space.
Once logged in you should see the space options displayed in the upper right corner near the user’s avatar. In the following image it is listed as dev and is currently selected. Source control configuration that follows will be applied to this space, dev.

SCM22

The next step involves going to Settings > Source Control > Github. This will present the following dialog to enter in the Github App and Repo settings. The App ID is available within the GitHub App settings. The App Installation ID is the trailing number that can be found in the URL for the GitHub App. The App Private Key is generated in the GitHub App and needs to be base64 encoded. Follow these instructions in Retool docs to generate the base64 encoded value.

SCM3

Verify the details are correct by selecting the Test connection button. If successful, select Save and deploy. This will then display status regarding the Github health and deploy and creates a Git commit listed under the Deploy section.

SCM4

The display also provides details of the commit in the Source Control console.

SCM5

Test Commit / Pull Request

Once the repository is connected, to test the connectivity we can then develop a simple app and leverage this repo to track work progress. This is referred to as a protected app in Retool.

Create a simple app in Retool. On the Retool Home Page in the dev space, select Create app and provide a name of retoolApp1.

SCM6

Create a clear canvas and then drag and drop a Table(new) onto the canvas as shown in the following figure.

SCM7

Next select the Settings (...) in the upper right corner of the IDE.

SCM8

Select Protect app.

SCM9

Select Protect application. This will display a message indiciating success in creating a branch with the initial commit. Select Open pull request to start the merge process.

SCM10

This will create a PR in GitHub and opens a browser with the Open a pull request dialog as shown in the following figure. Update the description and select Create pull request.

SCM11

Once the pull request has been created, select Merge pull request.

SCM12

This will then merge the initial commit into the branch defined in the GitHub connection setup. In this example the main branch is employed and the merge is displayed:

SCM13