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

Pull-request–based workflows in Retool let you treat your internal tools just like any other software project: you edit in branches, open PRs in GitHub or GitLab, get reviews, and then merge to deploy. Setting up Retool source control with GitHub or GitLab is a one-time configuration that connects your Retool org to a Git repository and enables branch-based editing for apps, queries, and other resources.

Below is a step‑by‑step guide to connect Retool to GitHub/GitLab, structure your repo, and use PRs to manage changes.

1. How Retool source control works

Retool’s source control integration is built for branch-based, PR-driven workflows:

Retool → Git: Retool serializes apps, modules, resources, and workflows into JSON/YAML (or similar) config files and syncs them to a Git repo.
Branches: Each branch in your GitHub/GitLab repo corresponds to a branch you can work on in Retool.
PRs as change gates: Changes made in Retool are committed to a feature branch. You open a PR in Git. Once approved and merged into your main branch, Retool can deploy those changes to your production environment.
Audit & history: Git becomes your audit log and history of changes, while Retool’s own audit logs track user actions and query executions inside the platform.

This means you continue to get Retool’s drag-and-drop editor while benefiting from Git-based workflows, code reviews, and CI/CD.

2. Prerequisites

Before configuring source control, make sure you have:

A Retool organization with source control enabled (typically on Business or Enterprise plans).
Admin access in Retool.
Admin or maintainer permissions in the GitHub or GitLab project you will connect.
A dedicated Git repository (or a folder within a monorepo) to store Retool configuration.

Optional but recommended:

A clear branch strategy (e.g., main/master for production, develop or staging for pre-prod).
Existing staging and production resources in Retool (databases/APIs), so you can map Git branches to the correct environments.

3. Create and prepare your Git repository

You can use either a new repo or an existing one. The examples below assume a GitHub repo, but the structure is similar for GitLab.

Create the repo
- GitHub: New repository → name it something like retool-config or internal-tools.
- GitLab: New Project → choose a similar name.
Decide on structure

A common structure is:
```
retool-config/
  apps/
    sales-dashboard.json
    admin-panel.json
  modules/
  resources/
  workflows/
  .gitignore
  README.md
```
You don’t need to create all these files manually—Retool will populate them after you connect—but decide on whether Retool gets its own repo or lives in a subfolder of a monorepo, like:
```
my-company-monorepo/
  backend/
  frontend/
  retool/
    apps/
    resources/
```
Set default branches
- Ensure your main production branch is set (e.g., main or master).
- If you use a staging branch (develop, staging), create it now.

4. Connect Retool to GitHub or GitLab

4.1. Configure source control in Retool

Open Retool Admin settings
- In Retool, go to Settings (or Admin Panel, depending on your plan).
- Look for a Source control or Git section (this is where the “Source control – branch-based editing” feature lives).
Select provider
- Choose GitHub or GitLab as the provider.
Authenticate

You will usually be prompted to either:
- Install a GitHub App (for GitHub), or
- Provide an OAuth token or personal access token (for GitHub/GitLab), or
- Connect via SSH (less common, depends on your Retool version).
Make sure the token or app has:
- repo scope (read/write) for GitHub.
- Equivalent repository read/write permissions for GitLab.
Choose repository
- From the authenticated account/org, select the repository that will store Retool configuration.
- If using a monorepo, specify the subdirectory (e.g., retool/).
Set branch mappings

Configure how Retool branches map to Git branches and environments:
- Production branch: typically main or master.
- Staging branch: e.g., staging or develop.
- Optionally, additional branches for long-lived environments.
These mappings determine which Retool resources (staging vs. production) are used when you run apps in a given branch.

5. Map branches to Retool environments and resources

Retool supports staging & production resources, letting you test apps against non-production databases or APIs, then switch to production when in user mode.

Define resource environments

For each database or API resource (Postgres, MySQL, REST APIs, Slack, etc.):
- Configure a staging resource connection.
- Configure a production resource connection.
Connect branches to environments

In the source control settings:
- Map staging branch → staging resources.
- Map main branch → production resources.
This ensures that when developers open an app from the staging branch, all queries run against staging databases/APIs. After merging to main, users see the same app wired to production resources.

6. Enable branch-based editing in Retool

Once Git is connected, you can work directly in branches inside Retool.

Choose the branch in Retool
- Open the Retool editor.
- Use the branch selector (often at the top of the editor) to:
  - Create a new branch (e.g., feature/add-customer-filter).
  - Switch between main, staging, and feature branches.
Create or modify apps
- Build or edit apps using Retool’s drag-and-drop interface.
- Add queries to databases or APIs, using staging resources when on the staging branch.
- Save your changes.
Commit changes to Git

Depending on your Retool version, commits may be:
- Automatic on publish, or
- Triggered explicitly via a “Commit” or “Sync to Git” action in the UI.
Choose a clear commit message (e.g., feat: add new customer health dashboard).

7. Creating PR-based changes with GitHub or GitLab

With branch-based editing enabled, your day-to-day flow becomes PR-centric.

7.1. Developer workflow in Retool + Git

Create a feature branch
- In Retool, create a branch: feature/add-invoice-report.
- Retool will create this branch in GitHub/GitLab under the same name.
Implement changes
- Build or modify apps/modules/workflows in that branch.
- Validate that queries run correctly against staging resources.
Sync to Git
- Commit changes in Retool.
- Retool pushes these changes to the corresponding branch in your Git repo.
Open a Pull Request / Merge Request
- In GitHub or GitLab, open a PR/MR from feature/add-invoice-report into staging or main (depending on your process).
- The PR will show diffs of the JSON/YAML files representing your Retool apps and resources.
Code review
- Reviewers examine the PR for:
  - Schema or resource changes.
  - App logic and query modifications.
  - Security or access control issues.
- Optionally, run CI checks (linting, schema validation, etc.) against the config files.
Merge to staging branch
- Merge the PR into your staging branch.
- Retool pulls the latest version from the staging branch.
- Test the app in Retool’s staging environment with staging databases/APIs.
Promote to production
- Once validated, open a PR from staging → main (or from feature/* → main if you don’t use separate staging).
- Merge the PR.
- Retool syncs from main, and users see updated apps running on production resources.

8. Handling conflicts and resolving issues

Sometimes multiple changes collide in Git. You handle these like any other Git-based project.

8.1. Merge conflicts in Retool config files

If GitHub/GitLab shows conflicts:

Pull latest changes locally (if you use a local clone of the repo) or use the web editor.
Open the conflicting JSON/YAML files.
Resolve conflicts manually, keeping the correct parts of each change.
Commit and push the resolved files.
Retool will then sync the resolved configuration from the branch.

Because Retool serializes app configuration, changes are often localized. Still, a good practice is to keep feature branches short-lived to minimize conflict complexity.

9. Best practices for PR-based workflows with Retool

To keep your Retool + GitHub/GitLab setup maintainable:

Use small, focused PRs
- Group related app changes together.
- Avoid “mega PRs” that touch dozens of apps at once.
Standardize branch naming
- For example:
  - feature/* for new functionality.
  - fix/* for bug fixes.
  - chore/* for refactors or config updates.
Require reviews on main/staging
- Use GitHub/GitLab branch protection rules to require:
  - At least one approval.
  - Status checks to pass (if you add CI).
Document the workflow
- Add a README.md in your Retool repo describing:
  - How to create branches from Retool.
  - How to open PRs.
  - Which branches correspond to staging and production environments.
Leverage Retool’s audit logs and usage analytics
- Git provides a history of file changes.
- Retool’s audit logs help you track:
  - Which user ran which query.
  - Which user modified which app and when.
- Usage analytics help you monitor whether changes are actually used across apps and users.

10. Example: End-to-end PR-based change

Here’s what a typical change might look like end-to-end:

Initiate
- Product request: “Add a new filter to the Admin Panel for high-value customers.”
Branch & develop
- In Retool: Create feature/high-value-customer-filter.
- Implement the filter and adjust queries on staging resources.
- Commit from Retool to the feature/high-value-customer-filter branch.
PR to staging
- Open PR: feature/high-value-customer-filter → staging.
- Reviewer checks diff, approves.
- Merge PR.
Test in staging
- Retool auto-syncs staging.
- QA tests the Admin Panel in staging, ensuring queries behave correctly and performance is acceptable.
Promote to production
- Open PR: staging → main.
- Merge PR after final approval.
- Retool syncs main, and the new filter is live for users against production databases.

11. Summary

To set up Retool source control with GitHub or GitLab for PR-based changes:

Create and prepare a Git repository dedicated to Retool config (or a folder in a monorepo).
Connect Retool to GitHub/GitLab via the Source control settings, selecting provider, repository, and branch mappings.
Map Git branches to Retool environments (staging vs. production) and ensure staging/production resources are configured.
Use branch-based editing in Retool, committing changes to feature branches that sync to Git.
Open PRs in GitHub/GitLab, review and merge into staging/production branches to deploy changes.
Rely on Git + Retool audit logs for traceability and controlled, PR-based internal tooling changes.

This setup brings your internal tools into the same Git-based, PR-driven lifecycle you use for the rest of your software, while still taking full advantage of Retool’s fast, low-code building experience.