Version and release apps
Learn how to version apps or revert changes to a previous state.
You can use the Releases feature to version and release apps. Each release has its own version number and reflects the app's state at that specific point in time. 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.
Any changes 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. This version isn't numbered and is referred to as latest.
Releases
You can version the current state of Retool apps and release them to users. Whenever you publish a release, it becomes the live version in user mode. You can change the published release at any time, create draft releases, and revert the current working version to changes from an earlier version.
After you publish the first release for an app, you can make changes to the current working version without affecting users.
Manage releases
You can access the Releases settings in two ways:
- Click the Releases and history icon in the left panel.
- 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.
| Property | Description |
|---|---|
| Version number | The version number for the release (e.g., 1.0.2). |
| Description | The description for the release. |
| Author | The Retool user who created the release. |
| Last published date | When the release was last published. |
| Last changed date | When the release was last modified. |
Use {{retoolContext.pageTag}} to reference the version number in the app.
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. You can click the Releases and history icon in the left panel, or click on the app version in the status bar.
Publish a release
You can create a release and publish it immediately, or publish an existing release at any time. Click the Releases and history icon in the left panel and use the ••• menu to publish a 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.
To view previous versions of an app, a user must belong to a permission group which has the Allow access to unpublished versions setting enabled. When this setting is not enabled, apps only show the most recently published version.
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 and . You can also browse the app's entire history and revert to a previous state.
Click the Releases and history icon in the left panel and select the History tab. This tab contains a list of history points that reflect each set of changes saved to the current working version.
| Property | Description |
|---|---|
| Description | The changes made to the app. |
| Author | The Retool user who made the changes. |
| Date | The date when changes were made. |
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.