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 the "Create new branch" option.

You should now be in the Retool editor. In the top right you can see that you're now editing the application on a branch. Changes made on branches won't affect the existing application.

The branch name has been generated for you automatically. If you'd like to pick a different name, open the application menu and click "Rename branch" under the "Actions" menu.

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

If you're happy with the changes, use GitHub to merge them into the main branch of your repository. In this case I'm squashing my commits. Your merge button may also say "Merge pull request" or "Rebase 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

An application can be unprotected at any time. In the application menu on the Apps page, select "Remove protection". A dialog will pop-up to confirm your decision.