How do I set up Retool source control with GitHub/GitLab for PR-based changes?

Pull request–based workflows are the safest way to roll out Retool app changes at scale. By connecting Retool source control to GitHub or GitLab, you can review diffs, enforce approvals, run CI checks, and keep a full history of every change to your internal tools.

This guide walks through how to set up Retool source control with GitHub/GitLab for PR-based changes, plus how to use it day-to-day.

How Retool source control works (high-level)

Retool’s source control integrates with Git-based workflows so you can:

Store Retool apps, modules, and other configuration as JSON in a Git repo
Use branches for changes instead of editing directly in production
Open pull requests in GitHub/GitLab, get code review, and merge
Sync changes back into Retool after merge

At a high level, the flow looks like this:

Connect Retool to a GitHub or GitLab repository.
Choose a main branch (usually main or master) as the production source of truth.
Developers create feature branches in Git, then sync those branches into Retool for editing.
Changes made in Retool generate commits to the feature branch.
A pull request is opened on GitHub/GitLab for review.
After approval and merge, Retool syncs from the main branch and updates your apps.

Prerequisites

Before you set up Retool source control with GitHub/GitLab for PR-based changes, make sure you have:

A Retool organization with Source control enabled (available on certain plans).
Admin or appropriate permissions in Retool to configure source control.
A GitHub or GitLab repository dedicated to Retool configuration (recommended to keep it separate from app/backend code).
Permissions in GitHub/GitLab to:
- Create and configure repositories
- Add deploy keys or OAuth apps / integrations
- Create and merge pull requests

Step 1: Prepare your GitHub or GitLab repository

Create a repo
- GitHub: Create a new private repository (recommended) such as retool-config or retool-apps.
- GitLab: Similarly, create a new project, preferably private.
Decide on a main branch
- Use main or master as your production source of truth.
- Protect this branch in GitHub/GitLab:
  - Require pull requests
  - Require approved reviews
  - Optionally require status checks (CI)
(Optional) Organize by directory structure
You can keep Retool content organized by folders, for example:
- apps/ – individual Retool apps
- modules/ – shared modules
- workflows/ – Retool Workflows
- resources/ – resource and environment config (if exported)

Retool will write JSON files into the repo and handle most structure details, but having a clear pattern helps with PR review.

Step 2: Connect Retool source control to GitHub or GitLab

The exact UI may vary slightly, but the general process is:

Open Retool settings
- In Retool, go to Settings (or Org settings / Admin depending on your version).
- Navigate to Source control.
Choose your provider
- Select GitHub or GitLab as your source control provider.
Authenticate Retool
- GitHub:
  - You may be asked to install the Retool GitHub App or authorize via OAuth.
  - Grant access to the specific repository you created for Retool.
- GitLab:
  - Authorize Retool with your GitLab account or set up a personal access token / application with repo access.
Select the repository
- In the Retool source control settings, choose the repository you prepared.
- Confirm the default branch (e.g., main) that Retool should treat as the canonical source.
Save and test connection
- Save the configuration.
- Retool should confirm that the connection to GitHub/GitLab is successful.

Step 3: Configure branch-based editing for PR workflows

To use PR-based changes, you’ll rely on Git branches rather than direct edits to the main branch.

Set the main branch as production
- In Retool, ensure your default source control branch is set to main (or your chosen production branch).
- Treat this branch as “production configuration” for your Retool apps.
Enable branch-based workflows
- Retool supports branch-based editing processes that are compatible with Git.
- Make sure the option to work on branches (instead of only the main branch) is enabled in your source control configuration.
Decide on branch naming conventions
- Common patterns:
  - feature/<short-description>
  - bugfix/<ticket-number>
  - hotfix/<issue>
Align with your resource environments
- If you use staging & production resources in Retool:
  - Connect your staging Retool environment to the same repo but use a staging branch if desired, or
  - Use the same branch but different underlying data resources (staging databases/APIs) to test app behavior.

Step 4: Typical PR-based development workflow in Retool

Once Retool source control is connected to GitHub/GitLab, your day-to-day flow looks like this:

4.1 Create a feature branch in Git

In GitHub/GitLab (or locally), create a new branch from main, for example:
- feature/new-approval-dashboard

Push the branch to your remote repository.

4.2 Switch to the branch in Retool

In the Retool editor:
- Open the app (or create a new one).
- Use the source control selector to switch from main to your feature branch.
- If the branch doesn’t exist yet in Retool, you may be prompted to create it based on main (depending on your setup).

Now you’re editing Retool apps in the context of that Git branch.

4.3 Make and test changes in Retool

Use Retool’s drag-and-drop UI and query editor to:
- Modify components and layout
- Update queries and transformers
- Edit modules or workflows

Your changes are stored in the branch and can point to staging resources (staging databases/APIs) for safe testing.

4.4 Commit and push changes from Retool

When you’re ready:
- Use the source control panel inside Retool to see a diff of your changes.
- Add a commit message (e.g., “Add approval dashboard filters and export CSV”).
- Commit from Retool; the commit will be pushed to the GitHub/GitLab branch.

Retool writes JSON changes into the repo, so your PR will show human-readable diffs of app configuration.

4.5 Open a pull request in GitHub/GitLab

Go to GitHub/GitLab and open a PR:
- Base branch: main
- Compare branch: your feature branch

In the PR:

Review JSON changes to apps, modules, and workflows.
Request reviews from teammates.
Run CI checks if you have automated tests or static analysis.

This is where your PR-based process enforces code quality and approvals before Retool apps change for end users.

4.6 Merge and sync back to Retool

After approvals, merge the PR into main.
Retool will:
- Detect the changes in the main branch (depending on your sync settings).
- Update the corresponding apps in your Retool organization to match the merged configuration.

If your organization uses staging & production resources, you can:

Validate on a staging Retool environment first (pointed at staging data).
Then deploy to production by syncing production Retool to the main branch and switching to production resources.

Step 5: Best practices for Retool + GitHub/GitLab PR-based changes

Following these practices will make your source control setup more reliable and maintainable:

Use protected main branches

Protect main in GitHub/GitLab:
- Require pull requests
- Require at least one review
- Disallow direct pushes
This ensures all Retool changes go through a PR-based workflow.

Keep staging and production in sync

Use staging & production resources in Retool:
- Staging app environment → staging DB/API resources
- Production app environment → production DB/API resources
Test app behavior in staging before merging PRs that update production configuration.

Introduce code owners

Use CODEOWNERS files in GitHub/GitLab:
- Assign owners to directories (e.g., /apps/billing/* → billing team).
- Enforce that domain experts approve changes to their apps.

Use descriptive commit messages and PR descriptions

Make it easy to understand why a Retool change occurred:
- Include ticket numbers (e.g., PROD-214) in commit messages.
- In PR descriptions, link to product specs or internal docs.

Reuse queries via a query library

Use Retool’s Query library to:
- Build and share reusable queries across apps.
- Keep logic centralized and easier to review in PRs.

Leverage audit logs and usage analytics

Use audit logs to track:
- Which queries run against databases/APIs via Retool.
- Who changed what and when in Retool.
Use usage analytics to:
- See which apps are most used.
- Prioritize refactors and improvements via branch-based workflows and PRs.

Troubleshooting common issues

Retool can’t access my GitHub/GitLab repo

Verify:
- The Retool integration or OAuth app has access to the specific repo.
- The repo is not archived or restricted beyond what the integration supports.
Reconnect the integration from Retool’s Source control settings.

Branch doesn’t show up in Retool

Make sure the branch has been pushed to the remote repo.
Refresh or reopen the Retool app.
Confirm you’re looking at the same repository and project in your source control settings.

Conflicts when merging

Resolve conflicts in GitHub/GitLab:
- Edit the conflicting JSON files.
- Ensure valid JSON after resolving.
After merging, trigger a sync in Retool to pull the latest state.

Changes not appearing in Retool after merge

Confirm:
- The PR was merged into the correct main branch.
- Retool is configured to use that branch as the source of truth.
In Retool’s source control panel, manually sync from the main branch if needed.

When to use PR-based changes for Retool

You should set up Retool source control with GitHub/GitLab for PR-based changes when:

You have multiple developers or teams editing apps.
You need strict review and approval for internal tool changes.
You want full traceability and version history of Retool configuration.
You already use GitHub/GitLab for other application code and want a unified workflow.

By treating Retool apps as versioned artifacts in Git and running all changes through pull requests, you gain the same level of control, safety, and auditability you expect from production-grade software development—applied to your internal tools.