How to Use Version Control in Retool

The Release Manager is your primary version control tool. Access it from the Retool editor: click the three-dot menu (⋮) in the top-right toolbar → Manage Releases (or Deploy → Manage Releases). The Release Manager shows a chronological list of all published releases with: - Release timestamp - Release notes (if you wrote them) - Who published the release - Status indicator (current active version is highlighted) Click any release to see its details. Click 'Activate' to make that release the current version — this is an instant rollback.

Every time you're ready to push changes to users, publish a release with a descriptive note. In the Release Manager → Create Release → Release notes field, write a human-readable description of what changed. Good release notes: 'Added date range filter to orders table', 'Fixed: pagination breaking on mobile layout', 'Updated: sales rep column now shows full name instead of ID' Release notes are your git commit messages in the Retool release system. They're the only context you have when investigating which release introduced a bug three weeks later.

1// There's no code for publishing releases — it's done via UI.
2// But here's the release workflow checklist:
3
4// 1. Edit app in editor (draft mode)
5// 2. Test in Preview mode (Staging environment)
6// 3. Switch to Production environment, test read-only
7// 4. Click Deploy button or ⋮ → Manage Releases
8// 5. Click 'Create Release'
9// 6. Write release notes: '[type]: [description]'
10//    Examples:
11//    'feat: Add bulk export to CSV button'
12//    'fix: Corrected pagination offset calculation'
13//    'chore: Update query to handle null values'
14// 7. Publish

When a deployed release causes issues, roll back immediately: 1. Open Manage Releases 2. Identify the last known-good release (the one before the problematic one) 3. Click the three-dot menu next to that release → Activate (or Rollback/Set Active) 4. Confirm the rollback The previous release becomes immediately active. Users refreshing the app URL will run the rolled-back version within seconds. No deployment pipeline, no cache clearing, no downtime required.

For Enterprise Retool, Source Control syncs app definitions to Git. Setup: 1. Go to Settings → Source Control 2. Click 'Configure Source Control' 3. Choose your provider: GitHub or GitLab 4. Authenticate with OAuth (GitHub App recommended for organizations) 5. Select or create a repository for your Retool apps 6. Choose the default branch (usually 'main') 7. Click Save Retool immediately syncs all existing apps to the repository as YAML files in a /resources/apps/ directory structure. Each app becomes a separate YAML file.

With Source Control configured, app changes can follow a branch-based workflow: 1. In the Retool editor, look for the branch selector in the toolbar (shows current branch name) 2. Click it to create a new branch or switch branches 3. Make app changes on the feature branch 4. In GitHub, create a pull request from your feature branch to main 5. Colleagues review the PR (Retool app YAML changes are diffable) 6. Merge the PR — Retool automatically deploys the merged changes to the active environment This gives your engineering team visibility into all Retool app changes through their standard code review workflow.

1# After Source Control is set up, app changes appear as YAML commits:
2# Example: what a Retool app YAML change looks like in a PR diff
3
4# --- a/resources/apps/orders-dashboard.yaml
5# +++ b/resources/apps/orders-dashboard.yaml
6# @@ -45,7 +45,7 @@
7#  queries:
8#    fetchOrders:
9#      query: |
10#  -      SELECT * FROM orders LIMIT 100
11#  +      SELECT * FROM orders WHERE status = 'pending' LIMIT 500
12
13# This is a reviewable, diffable change that follows standard
14# pull request review processes.

Protected Apps (Enterprise) adds a mandatory approval step before any Retool release can go live. It's analogous to requiring PR approval before merging. Enable it: Settings → Permissions → Protected Apps toggle. Configure: which Groups can approve releases, whether approved releases auto-deploy or require a final manual publish step. With Protected Apps: - Editors propose a release (like opening a PR) - Designated reviewers receive a notification - Reviewers test the proposed release in a preview/staging URL - Reviewers approve or reject - Only approved releases are published to users