Configure protected resources

Learn how to protect and sync resources using Source Control.

πŸ“˜

Protected resources are available on Enterprise Self-hosted Retool deployments on version 2.110 or later.

Using protected resources in Source Control, you can safely replicate resource configurations across multiple instances of Retool, similar to protected applications. You can use protected resources with any of Retool's supported source control management (SCM) providers:

Each protected resource configuration is represented as a YAML file.

Prerequisites

Before you configure protected resources, you must set up your Source Control provider.

If your resources depend on secret values, set the secrets as environment variables using the RETOOL_EXPOSED prefix. The RETOOL_EXPOSED value is then included in the synced resource YAML file. Values that are encrypted and hidden in the resource configuration UI are not synced unless they are added as RETOOL_EXPOSED variables.

Protect resources

To protect a resource and start tracking its changes, you need to merge an initial commit for the resource to your remote repository.

1. Create a branch

You can start protecting your resource by selecting Protect resource from either:

  • The Resources overview page (/resources).
  • The individual Edit resource page.

Protect resource from overview page

When you click Protect Resource, Retool creates a new branch on your SCM provider.

Start protecting resource overview

2. Open a new pull request

After you click Open pull request, you’ll be redirected to your SCM provider to create an initial commit for the resource. This commit contains a YAML file with configuration details for your resource.

Open initial pull request for protected resource

3. Merge pull request

Resources are not protected until your repository contains the resource YAML file from your initial commit. After you merge this commit, the resource syncs to all other instances.

Edit protected resources

When you edit a protected resource, the Resources overview and the Edit resource pages display a warning that your resource has unmerged changes. This warning displays until you merge your changes to your remote repository.

Open PR for unmerged changes

To create a pull request, click the Open PR button next to the resource. Follow your source control workflow to merge the pull request. After it’s merged, you’ll see the resource in all your instances, with the resource updated as necessary.

To rename a resource, from the Resources overview page, select Rename next to the resource. You must commit any renaming changes to your SCM provider before they take effect locally.

Unprotect resources

You can unprotect a resource from either:

  • The Resources overview page (/resources).
  • The individual Edit resource page.

A resource must be unprotected before you can delete it.

Protected resources with multiple environments

Only the changes on the production environment of a protected resource are tracked in source control, even if you use multiple environments. This is because multi-instance Retool deployments typically only use a single environment in their downstream (non-development) instances. If your setup uses another configuration, contact Retool Support.