# How to Use Version Control in Retool

- Tool: Retool
- Difficulty: Beginner
- Time required: 15-20 min
- Compatibility: Retool Cloud and Self-hosted
- Last updated: March 2026

## TL;DR

Retool has two version control mechanisms: the built-in Release Manager (all Retool plans) which stores published app versions for instant rollback, and Source Control via Git (Enterprise) which syncs app definitions to a GitHub/GitLab repository for PR-based deployments. For most teams, the Release Manager provides sufficient version control. Enterprise teams needing code review workflows use Source Control.

## Version Control in Retool: Releases and Git Source Control

Retool's version control comes in two layers. The first — available on all plans — is the Release Manager. Every time you publish a release, Retool stores an immutable snapshot of the app. You can view the release history, compare versions, and instantly activate any previous release to roll back changes. This is sufficient for most teams.

The second layer — Source Control, available on Enterprise plans — syncs Retool app definitions to a Git repository (GitHub or GitLab). App changes become commits, pull requests become deployment approvals, and your standard software development workflow applies to no-code/low-code app changes. This bridges the gap between Retool and your engineering team's existing GitHub-based workflows.

This tutorial covers both layers, helping you use releases effectively and set up Source Control if you're on an Enterprise plan.

## Before you start

- Editor or Admin access to a Retool app
- For Source Control: Enterprise Retool plan and a GitHub or GitLab account
- For Source Control: repository creation permissions in GitHub/GitLab
- Basic understanding of Git concepts (branch, commit, pull request) for the Source Control section

## Step-by-step guide

### 1. View and use the Release Manager

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.

**Expected result:** You can see all previous releases listed in chronological order with timestamps and release notes.

### 2. Publish releases with meaningful version notes

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.

```
// There's no code for publishing releases — it's done via UI.
// But here's the release workflow checklist:

// 1. Edit app in editor (draft mode)
// 2. Test in Preview mode (Staging environment)
// 3. Switch to Production environment, test read-only
// 4. Click Deploy button or ⋮ → Manage Releases
// 5. Click 'Create Release'
// 6. Write release notes: '[type]: [description]'
//    Examples:
//    'feat: Add bulk export to CSV button'
//    'fix: Corrected pagination offset calculation'
//    'chore: Update query to handle null values'
// 7. Publish
```

**Expected result:** A new release appears in the Release Manager with your release note and a timestamp.

### 3. Roll back to a previous release

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.

**Expected result:** The Release Manager shows the previous release as the active version. Users immediately see the rolled-back version.

### 4. Set up Source Control (Enterprise: connect to GitHub)

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.

**Expected result:** The GitHub repository contains YAML files for each Retool app. Changes to apps create new commits in the repository.

### 5. Create branches and use pull requests for deployments

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.

```
# After Source Control is set up, app changes appear as YAML commits:
# Example: what a Retool app YAML change looks like in a PR diff

# --- a/resources/apps/orders-dashboard.yaml
# +++ b/resources/apps/orders-dashboard.yaml
# @@ -45,7 +45,7 @@
#  queries:
#    fetchOrders:
#      query: |
#  -      SELECT * FROM orders LIMIT 100
#  +      SELECT * FROM orders WHERE status = 'pending' LIMIT 500

# This is a reviewable, diffable change that follows standard
# pull request review processes.
```

**Expected result:** App changes appear as YAML diffs in pull requests. Reviewers can approve or request changes before the update goes live.

### 6. Configure Protected Apps for mandatory code review

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

**Expected result:** A release approval workflow is enforced. No changes reach production users without explicit reviewer approval.

## Complete code example

File: `Scripts → release-checklist.sh (documentation template)`

```bash
#!/bin/bash
# Retool Release Checklist — Run before every production deployment
# Copy this checklist and use it before creating a release

echo "=== Retool Release Checklist ==="
echo ""
echo "1. CODE REVIEW:"
echo "   [ ] All queries tested in Preview mode (Staging environment)"
echo "   [ ] No console.log() debug statements in JS queries"
echo "   [ ] Error handling (On Failure) configured on all write queries"
echo "   [ ] Code reviewed by at least one other team member (for Protected Apps)"
echo ""
echo "2. ENVIRONMENT:"
echo "   [ ] Staging environment validated: all queries return expected data"
echo "   [ ] Production environment tested read-only: connections work"
echo "   [ ] Config vars set for production environment (Settings → Config Vars)"
echo "   [ ] Resource credentials configured for production"
echo ""
echo "3. PERMISSIONS:"
echo "   [ ] User Groups with access verified (Settings → Permissions)"
echo "   [ ] No test accounts in Editor access that shouldn't be there"
echo "   [ ] App URL shared with correct stakeholders (not editor URL)"
echo ""
echo "4. RELEASE:"
echo "   [ ] Release notes written describing all changes"
echo "   [ ] Release created in Manage Releases"
echo "   [ ] Post-deployment smoke test completed (open app as end user)"
echo ""
echo "All checks done? You're clear to deploy."
```

## Common mistakes

- **Not writing release notes and then being unable to identify which release introduced a bug** — undefined Fix: Make it a team rule: no release without notes. Even 'Minor text fixes' is better than nothing. For larger changes, write a bullet list of what changed. Notes appear in the Release Manager and are your deployment log.
- **Assuming Source Control (Git sync) is available on all Retool plans** — undefined Fix: Source Control is an Enterprise feature. For lower-tier plans, use the built-in Release Manager for version control. The Release Manager provides timestamps, release notes, and instant rollback — sufficient for most teams.
- **Confusing app version history (Release Manager) with Retool's database backup/snapshots** — undefined Fix: The Release Manager only stores app definition versions (UI, queries, event handlers) — not the underlying database data. If your Retool Database (managed Retool backend) has data corruption, that's handled separately via Retool Database backups, not app releases.

## Best practices

- Write release notes for every release — they're the only audit trail you have on plans without Source Control
- Treat Retool releases like git tags: create them at meaningful milestones, not after every minor change
- Keep at least 5 previous releases available for rollback — Retool stores all releases indefinitely, so no action needed on your part
- For Enterprise teams, align Retool Source Control branches with your application code branches (e.g., Retool feature branch = same name as backend API feature branch)
- Use Protected Apps for any Retool app handling financial transactions, medical records, or PII — mandatory review reduces risk of accidental data exposure
- After rolling back, investigate the broken release in a duplicate/copy of the app before fixing and re-releasing
- Document which Retool app maps to which GitHub repository directory in a team wiki or README

## Frequently asked questions

### How many previous versions does Retool keep in the Release Manager?

Retool stores an unlimited history of all published releases — there's no automatic pruning. Every release you've ever published remains in the Release Manager and can be reactivated at any time. This means you always have a rollback target regardless of how old the last stable release was.

### Can two editors make conflicting changes to the same Retool app simultaneously?

Yes, and this is a known limitation of Retool's collaborative editing model. If two editors make changes to the same app simultaneously, the last save wins — earlier edits can be overwritten. Retool does not have real-time conflict detection like Google Docs. Use Source Control (Enterprise) with branches to manage concurrent editing safely, or establish a team convention of one editor per app at a time.

### Does Source Control sync in real-time or only when I publish a release?

With Retool Source Control, app changes are synced to Git on every save in the editor (not just on release). This means your Git history captures every intermediate edit, not just published releases. You can configure which branch is the 'production' branch and use PR workflows to control what makes it into the active version for users.

---

Source: https://www.rapidevelopers.com/retool-tutorial/how-to-use-version-control-in-retool
© RapidDev — https://www.rapidevelopers.com/retool-tutorial/how-to-use-version-control-in-retool