Releases and history

Any edits you make to a Retool app are automatically saved to the current working version. This version is live to all users by default and immediately reflects your changes.

You can use the Releases feature to version and release app changes. Each release version has its own version number and reflects the app at a specific state. Once you publish a release, it becomes the live version with which all users interact. This allows you to safely test, build, and release changes without disruption.

Retool also maintains a complete history of changes. You can browse through the list of changes or versions, and revert an app to a previous state.

Working and live versions

The current working version reflects the latest changes to your app. This version isn't numbered and is referred to as latest.

👍

Use {{retoolContext.pageTag}} to reference the version number in the app.

The live version of an app is the version that users interact with in user mode. The current working version, latest, is used as the live version by default. Any changes you make to an app are saved to this current working version and immediately live. If you use releases to version an app, the live version is the currently published release version.

Releases

📘

Releases are only available on paid Retool plans.

You can version the current state of Retool apps and release them to users. Whenever you publish a release, it becomes the live version for all users. You can change the published release at any time, create draft releases, and revert the current working version to changes from an earlier version.

You can access the Releases settings in two ways:

• Click ••• in the App editor toolbar to open the App settings menu and select Releases and history.
• Click the published release version number displayed in the status bar.

The Releases tab contains information about release versions. The published release includes a Live tag.

Create a new release

Click Create new to create a version for release. Retool uses Semantic Versioning and automatically increments the version number based on your selection of Major, Minor, or Patch versioning.

Once you provide a description and selecting the version number to increment, you can create a draft release or create and publish a release immediately.

Create a new draft release

To create a draft release, click Create draft release.

A draft release is not initially published as the live version. This is useful if need to wait (e.g., conduct further testing) or are working on significant changes and may create subsequent releases before publication.

If you create a draft release and make further changes, you must create another release.

Create and publish a new release

To create and publish a new release, click the dropdown button and select Create and publish. The release is immediately published as the live version for all users.

Preview a release

You can preview a specific version of an app in user mode. There are a number of ways to do this, such as:

• Click ••• next to the release version in the Releases tab and select Preview release.
• Expand the dropdown menu next to the Preview button in the App editor and select a version.
• Click on the version number while previewing the app and select a different version.

Publish a release

You can create a release and publish it immediately, or publish an existing release at any time. Click ••• next to the release version in the Releases tab and select Publish release.

The release is immediately published as the live version for all users. Once published, the release displays the Live label.

Unpublish or delete releases

If necessary, you can unpublish a release by selecting Unpublish release. This action does not publish a previous release and restores the current working version, latest, as the live version for all users.

If your want to remove any releases and are certain they are no longer needed, you can also delete them permanently.

Open a previous version of an app

Use the _releaseVersion URL parameter to launch a specific release version of an app (e.g., _releaseVersion=1.0.2). Refer to the URL query parameters documentation to learn more.

Revert to a previous version

You can revert the current working version of your app to the state from a previous version. All changes since this version are discarded but still remain in the history. This does not affect any other releases and doesn't change the published release.

This is useful if you've made a series of changes in the current working version but want to revert the app to an earlier point.

Compare releases

You can compare changes between two different versions of your Retool app as a JSON diff. Click Compare changes, then select the Base and Compare versions to show for comparison. You can also switch between Unified or Split view modes.

History

Retool automatically saves changes to the current working version. You can undo or redo any changes you directly make to an app, such as moving a component or deleting a query, with Cmd/Ctrl+Z and Cmd/Ctrl+Shift+Z. You can also browse the app's entire history and revert to a previous state.

👍

Press Cmd/Ctrl+Shift+Y to quickly open the History modal.

Click ••• in the App editor toolbar to open the App settings menu and select Releases and history. The History tab contains a list of history points that reflect each set of changes saved to the current working version.

The first history point represents the latest state of the current working version. You can revert to any previous history point and restore your app to a previous state.

Revert changes

You can restore the current working version to an earlier state. Select a history point and click Revert. This discards all changes made after the selected point but does not remove them from the history.

Any time you revert changes, the reversion is also added to the history as Reverted changes. You can revert to a previous history point if you need to undo the reversion and restore changes back to the current working version.

Open an app at a previous history point

Use the _historyOffset URL parameter to launch an app in user mode that only contains changes up to a previous history point. The offset is zero-indexed, with 0 representing the current working version, and ordered from newest to oldest. The greater the value, the older the history point. Refer to the URL query parameters documentation to learn more.