Retool Source Control Explained for Teams

Why Retool Teams Break Without Source Control

Here is what the failure mode actually looks like. Your ops team has a Retool app that handles customer refunds. It started as one screen with a couple of queries. Over six months it grew into twelve components, four resource queries, two transformers, and a JavaScript function that nobody fully understands. Three people have edit access. One of them just fixed a bug directly in the production app without telling anyone. Another person is mid-edit on the same component right now. The third pushed a change yesterday that they think might have broken the refund confirmation email, but they are not sure because there is no history to check.

This is not a hypothetical. It happens to every team that scales Retool usage without any version discipline. The root cause is that Retool apps, by default, save changes instantly and globally. There is no staging. There is no review. There is no rollback. You click save and the change is live for every user immediately.

The other cost is team coordination. When multiple developers or even non-developer admins are touching the same Retool app, you need a way to isolate work in progress from what is currently serving users. Without source control, you are either serialising all work (one person edits at a time), or you are accepting that half-finished changes will be visible to users. Neither option scales.

What Retool Source Control Actually Does

Retool source control connects your apps to a Git repository — GitHub, GitLab, or Bitbucket. When you enable it on a Retool organisation, each app is serialised to a JSON file and committed to the repo. From that point on, changes to apps flow through Git like any other codebase. You get diffs, pull requests, history, and branch-based development.

Here is what source control concretely enables for your team:

• Pull request reviews for app changes. A developer makes changes on a branch, opens a PR, and a teammate reviews the diff before anything touches production. A reviewer can see that a SQL query was modified, read the change, and catch a missing WHERE clause before it runs against live customer data.
• Full change history. Every commit is a timestamped record of what changed and who changed it. When something breaks on Friday, you open the commit log, find the change from Thursday afternoon, and either revert or understand exactly what happened.
• Branch-based development. Developers can build features on isolated branches without affecting the production app. You can work in parallel on multiple features without them interfering with each other or with what users are seeing right now.
• Deployment control. Rather than every save going live immediately, you control when changes reach production by merging branches and deploying to specific Retool environments.
• Rollback capability. If a release breaks something, you can revert the commit in Git and redeploy the previous state. The ability to undo a bad deployment in minutes rather than trying to manually reconstruct what the app looked like before is worth the entire source control setup on its own.

What Source Control Does Not Magically Fix

It does not version your resources and credentials. Resources are configured at the organisation or environment level, not inside the app JSON. If your staging Supabase project and your production Supabase project use different resource names, your queries will break on deployment.

It does not migrate your database schema. You can version the Retool app perfectly, but if the app's SQL queries reference a column that does not exist yet in production, the app will fail. Your database migrations need to ship before or alongside the app deployment.

It does not handle secrets rotation. It commits the reference to environment variables, not the values. You need to separately manage the actual secret values in your Retool environment configuration.

It does not resolve conflicts intelligently. Retool app JSON is not designed for human-readable merging. If two developers modify the same component on different branches, the conflict will be a wall of JSON. Keep feature branches short-lived — days, not weeks.

It does not gate on test results by default. Retool does not have a native automated testing framework. Source control gives you the hook, but you have to build the testing layer yourself.

A Branching Strategy That Works for Retool Teams

Three Persistent Branches

Keep three long-lived branches: main, staging, and develop. Each maps to a Retool environment. main maps to production. staging maps to your staging environment. For smaller teams, two persistent branches — main and staging — is often enough.

Short-Lived Feature Branches

All new work happens on feature branches cut from staging. Name them with a convention that ties them to work: feature/refund-flow-approval, fix/customer-search-null-crash. Keep them short-lived. When a feature is ready, open a pull request from the feature branch to staging. At minimum, one other developer should review the diff and actually read the query changes.

Staging as the Gate to Production

Nothing goes to main except from staging. The merge from staging to main should be a deliberate act — a release decision — not an automatic pipeline step. Configure branch protection rules in GitHub: require pull requests, require at least one approval, and prevent direct pushes to both staging and main.

Hotfixes

Cut a hotfix branch from main, fix the issue, get a fast-tracked review, merge to main, and then back-merge to staging so the branches stay in sync. The back-merge step is easy to forget under pressure — build it into your incident checklist.

One Repository, Multiple Apps

If your team manages multiple Retool apps, keep them all in the same repository. Retool's source control exports each app as a separate JSON file in the repo, so they naturally co-exist. Keeping everything in one repo gives you a unified PR history and simplifies branch management.

Connecting Source Control to Environments, Databases, and Secrets

Retool Environments and Branch Mapping

When you connect source control, you map a Git branch to a Retool environment. The staging branch deploys to the staging environment. The main branch deploys to the production environment. This is configured in your Retool organisation settings. The mapping should be treated as infrastructure configuration — document it, put it in a README in the repo, and do not change it without a team conversation.

Use consistent resource naming across environments. A resource called postgres_customers should point to your staging database in the staging environment and your production database in the production environment, with the same resource name across both. Do not use different resource names per environment — it creates query-level bugs when you deploy the same app across environments.

Supabase Integration

For schema migrations, use Supabase's built-in migration tooling via the Supabase CLI. Your migration files should live in the same Git repository as your Retool apps, under a supabase/migrations/ directory. When you run a release, you apply migrations first, then deploy the Retool app. This ordering is critical. Deploying the app before the migration runs will cause queries to fail against the old schema.

The Supabase CLI command for applying migrations to a linked project is:

supabase db push --linked

Run that against your production Supabase project as the first step of a production release. If the migration fails, do not deploy the Retool app. Fix the migration, test it against staging, and then re-run the release.

Environment Variables and Secrets

Retool supports environment variables at the organisation level. Use them for anything that changes per environment: API base URLs, feature flags, third-party service identifiers. Actual secrets — API keys, service account credentials, database passwords — should never appear in your Retool app configuration or your Git repository. In Retool, credentials are stored at the resource level, encrypted, and not exported as part of the source control sync.