Skip to main content

Protect resources with Source Control

Learn how to protect and sync resources using Source Control.

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:

On Retool Cloud and self-hosted Retool versions 3.6.0 and later, Retool uses Toolscript to serialize resources. On earlier versions of Retool, protected resource configurations are represented as YAML files.

Prerequisites

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

If your resources depend on secret values, set the secrets using one of the following:

Protecting resources which use custom authentication is not supported.

Resources in multiple instances

To differentiate resources across instances, set the same variable names with different values per environment. For example, given a resource with different resource URLs for development and prod—e.g., the development URL dev-api.your-company.com and prod prod-api.your-company.com—you can use the following setup. You'd define URLs in this example in config vars or secrets manager settings, or wherever you store environment variables.

TypeExample settingExample usage in resource config
RETOOL_EXPOSED environment variablesRETOOL_EXPOSED_YOUR_COMPANY_API_URL%RETOOL_EXPOSED_YOUR_COMPANY_API_URL%
Config varyour_company_api_url{{ environment.variables.your_company_api_url }}
Value from secrets manageryour_company_api_url{{ secrets.your_company_api_url }}

The same resource can reference RETOOL_EXPOSED_YOUR_COMPANY_API_URL, {{ environment.variables.your_company_api_url }}, and {{ secrets.your_company_api_url }}, and different URL values are injected for each instance.

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.