Skip to main content
This page is unlisted and can only be accessed directly via URL. It is excluded from the site navigation and search results.

Multi-instance releases

Learn how to create and manage releases across instances

Version: Cloud and 3.178 Edge

Self-hosted Retool 3.123 Edge and later include support for managing releases of apps protected with Source Control. This feature enables teams to control the live release across various instances using a manifest stored in the Source Control repository.

  • This feature is applicable only to protected apps; unprotected apps use the existing release flow.
  • For now, this feature is limited to apps, with plans to support additional Retool elements (such as resources and workflows) in future iterations.

Demos:

  • Creating and updating releases (loom)
  • Publishing releases (loom)

Setup​

Feature flags​

To enable this feature, activate the following feature flags from the Settings > Beta page:

  • Multi-instances release artifacts to be stored in the source control repo
  • Multi-instances release artifacts to be deployed from the source control repo
  • Settings page for multi-instance releases
  • Multi-instances publish release based on manifest in source control repo
  • Multi-instance releases: public API

If you do not see these feature flags, reach out to support to be added to the private beta.

Source control setup​

Ensure that your source control provider is configured and enabled. Follow a Source Control tutorial for setup instructions. All Retool instances should be configured to point to the same branch in your source control.

Release artifacts​

The release artifact represents a snapshot of the app at the time the release is created. These artifacts are stored in the dist/apps/<app-uuid> directory within the source control repository.

Creating a new release​

To create a new release, use the Retool UI.
1. Click on the Latest button located in the bottom left corner to open the Releases and History modal.

2. Click the Create new button to create a new release.

3. Select the release Version and fill in the Description, then click the Create release PR button.

4. Verify that the release Version and Description are correct, then click Create branch with release artifact. You’ll see a loading screen while the branch is created.

5. Once the branch is created, you’ll see a success message. Click Open pull request to navigate to the pull request management page of your source control provider, where you can create and manage your pull request.

6. A success message indicates that the release will be available once the pull request is merged and deployed.

7. After the pull request is merged and deployed, the release candidate appears in the release list. Click the Latest button again to confirm that the release is now available.

Deleting a release​

Releases cannot be deleted from the UI. To remove a release, you must delete it directly from the repository.

1. Remove the artifact from the source control repository. Artifacts are located at dist/apps/<app-uuid>/<release-version>.zip.

2. After the artifact is deleted, it is removed from all instances in the next deployment.

Publishing a release​

With this new feature, the manifest defines which release version is live on each instance. To publish a release to a specific instance, simply update that instance's manifest.

Manifests​

The manifest file is essential for determining which release is live on each Retool instance. It should be located in the source control repo under the manifests/ directory. For each Retool instance (e.g., dev, prod), create a separate manifest file. The directory structure should look like this:

manifests/
├─ dev.yaml
└─ prod.yaml

Creating and updating the manifest​

Users can create and update the manifest programmatically with the release manifest endpoints. The manifest file includes the following elements:

  • Version: Version of the manifest (1.0.0 for now).
  • Name: The name of the instance controlled by this manifest, which should match the manifest file name.
  • Apps: An array containing the app UUID and release version for each protected app. Each entry should include:
    • uuid: Found in the metadata.json file for the app (look for the pageUuid field).
    • release: Specify either latest to track the latest release or the specific release version.

Example manifest:

version: 1.0.0 
name: production 
apps:  
  - uuid: <app-uuid> 
    release: latest  
  - uuid: <app-uuid>  
    release: 1.0.0

Selecting a manifest​

To select the manifest associated with an instance:

1. Navigate to the source control configuration page, and find the new Releases widget on the right side. Click on the Edit Config button.

2. The Edit release configuration modal displays all available manifests in the manifests/ directory of your source control repo. Select the desired manifest for the instance and click the Save button.

3. Once you select a manifest, it is displayed in the Releases widget.

Programmatic Access​

API endpoints allow programmatic access to release management in source control. These endpoints enable the management of manifests and release artifacts directly from the API.

A detailed overview is available here.

Token
Generate an API token with the necessary permissions from Settings > Retool API.

  • Source Control: Releases (read)
  • Source Control: Releases (write)