In this guide we'll go through the entire workflow for making a change to a protected Retool application.

📘

This guide assumes you already configured the Source Control settings for your Retool instance. It also uses GitHub as an example, but this feature supports multiple remote SCM providers.

Video Walkthrough

Watch a quick introduction to this feature by one of our engineers.

Step-by-step walkthrough

Our sample application is a customer dashboard. It has a title and a table view, which lists our customers. We'll be adding a detail view to the right side of the table.

Importing the application

If you don't have an existing Retool applications 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.

Protecting an application

Now that we have an application to edit, we need to enable protection. On the Apps page (https://retool.example.com/apps), locate the application. In the menu, select Protect app.

A confirmation dialog will pop up. Click Protect application.

Follow the flow to open and merge the initial PR of the app's source code into the connected Github repository.

Your application should now have a blue, protected badge next to its name. If you look closely, the Edit and Preview buttons are now dropdown buttons.

Creating a branch

Click Edit and select Create new branch.

This opens the App editor. The branch on which you're editing appears in the lower left. Changes made on branches don't affect the existing application.

Retool automatically generates a name for the branch. To rename it, click on the branch name and select Rename current branch. Edit the name and then click Rename branch.

Drag a key-value map next to the table and configure it to display the selected row of the table.

Committing changes

Now that you've finished making changes, we need to commit them and push them to GitHub. Click the Commit button in the top right corner. Write a description of your change. You'll also see a diff of your changes, which should include the new key-value component. If it all looks good, push them to GitHub by clicking the blue button.

Opening a pull request

Once you've committed your changes, you can open up a pull request to get your changes reviewed. Click the menu button to the left of the Commit button and select Open a pull request. You'll be redirected to GitHub to finish creating the pull request.

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

Merging changes

After completing your changes, use GitHub to 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 will show up in the main branch of the Retool application. Your detail view should show up right next to the table view.

Removing 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.