Skip to main content

Protect apps with Source Control

Learn how to make changes to apps protected with Source Control.

This guide outlines the end-to-end workflow required to make changes to a protected Retool app and merge these changes into the main branch.

Requirements​

Before you begin, ensure Source Control is configured for your Retool instance. This guide uses GitHub, but Retool supports multiple remote SCM providers.

Source Control is available on the Enterprise plan. You must be an admin to configure Source Control.

1. Import the app​

If you don't have existing Retool apps to edit, you can import the one used in this guide. First, download the protected-applications-tutorial.json file. Once it's saved, import it into Retool.

2. Protect the app​

In Retool, protected apps are apps checked into remote source control repositories. To protect your app, go to the App IDE and select ... > Protect app.

Click Protect application on the confirmation modal. Follow the flow to open and merge the initial PR of the app's source code into the connected GitHub repository.

Your application now shows a badge and Protected below its name.

3. Create a branch and make changes​

Click Edit and select Create new branch. Give the branch a descriptive name for your changes. You can also select Make collaborative to allow other users to push changes to it.

After you create the branch, you're directed to the App IDE. The branch on which you're editing appears in the lower left, along with the commit log for the branch. Changes made on branches are local to the branch.

Edit your app. In this example, you can update the table's search filter to include searching by email. Update the tableFilteredData transformer to the following query.

return formatDataAsArray({{getRows.data}}).filter((row)=> row.name.toLowerCase().includes({{nameAndEmailFilter.value}}) || row.email.toLowerCase().includes({{nameAndEmailFilter.value}}) )

Rename the placeholder text of the nameFilter to Search by name and email, and rename nameFilter to nameAndEmailFilter.

Images for protected apps are only stored in the database of the instance in which the app was developed. An image uploaded to the database for one app cannot be accessed by downstream environments.

To ensure that an image appears in all instances of your app, you can:

  • Host the image on a public URL that is accessible from all apps, and use the URL option for the image source.
  • Upload the image to the downstream database environments.

4. Commit your changes​

After you finish making changes, you need to commit them and push them to GitHub.

  1. Click the Commit button in the top right corner.
  2. Optionally, select Review changes to preview the changes in your commit.
  3. Write a description of your change.
  4. Push your changes to GitHub by clicking Commit to <your-branch-name>.

5. Open a pull request​

After you commit your changes, open a pull request to get your changes reviewed. Click branch name in the lower left corner, and select Create pull request.

Review any dependencies your app has on other protected objects, such as resources or modules. Click Open pull request to visit the pull request on GitHub.

Notice that the description is already populated with a link to preview your changes on your branch.

6. Merge changes​

After you commit your changes, merge them into the main branch of your repository. The merge button label may differ depending on your repository's configuration for merging (e.g., Rebase and merge or Squash and merge).

After a few seconds, your changes appear in the main branch of the Retool application.

Remove application protection​

You can remove protection for an application at any time. In the application menu on the Apps page, select Remove protection, then confirm changes in the dialog box that appears.