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:
- Secret configuration variables.
- Secrets manager integration, such as AWS Secrets Manager or HashiCorp Vault.
- Environment variables with the
RETOOL_EXPOSEDprefix.
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.
| Type | Example setting | Example usage in resource config |
|---|---|---|
RETOOL_EXPOSED environment variables | RETOOL_EXPOSED_YOUR_COMPANY_API_URL | %RETOOL_EXPOSED_YOUR_COMPANY_API_URL% |
| Config var | your_company_api_url | {{ environment.variables.your_company_api_url }} |
| Value from secrets manager | your_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.
When you click Protect Resource, Retool creates a new branch on your SCM provider.
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.
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.
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.