Skip to main content

Git Syncing is a legacy feature and should only be used if your organization cannot use any supported providers. Otherwise, Retool strongly recommends you set up Source Control instead for a simpler and more powerful integration.

Retool apps can be synced with a Git repository, letting you customize how you develop and deploy Retool apps across multiple environments and helping your team adhere to application development lifecycle best practices.

The most common approach is to have multiple instances of Retool representing multiple environments: development, staging, and production. Code promotion across environments is controlled via Git, so that every change must be reviewed as a pull request before being promoted to a higher environment.

With this approach, engineers can safely build Retool apps on the development instance as well as run tests & perform QA on the staging instance; end-users can access the applications on the production instance.

Only application code is synced between Retool and the Git repository. You will need to create resources manually in your non-development environment(s) for apps to work once promoted.

When recreating resources in non-development environments, it is important that you use the same resource name to ensure that queries in synced apps work as expected. See our document on secret management using environment variables to learn how to dynamically pass connection details into your resources.

It is also important that you use the same ENCRYPTION_KEY environment variable value across multiple git synced instances.

Git syncing overview

In the below diagram, the development instance is configured to continually push changes to a dev branch. The staging and production instances are configured to automatically watch and deploy code from the staging and master branches, respectively.

In this setup, engineers will only have access to build and edit applications on the development instance of Retool. The apps on the staging and production instances are locked from changes in the Retool user interface (i.e. the instance is read-only).

At your own cadence, you can merge changes from dev to staging to production.

Setting up Retool Git syncing with GitHub

We also support using GitLab, AWS CodeCommit, BitBucket, and Azure Repos. If you have any questions about getting these set up, don't hesitate to reach out to us directly!

As you set up Git syncing, note that this is a unidirectional process. Any individual Retool instance can either push changes to your Git repository or pull changes from it.

A typical setup will include:

  • A single development instance pushing changes to the dev branch of your GitHub repository
  • One or more additional instances reading from different branches of the same repository (e.g. a staging instance reading from a staging branch and a production instance reading from the main branch)

Configure a Retool instance to push changes to GitHub​

1. Create an empty Git repository​

In order to set up Git syncing, we'll need to initialize an empty repository following these steps:

Go to GitHub and create a new repository.

Create a new local directory and clone the repository:

git clone https://github.com/GITHUB_USERNAME/REPO_NAME.git

Navigate into the repository:

cd REPO_NAME

Create an empty commit using the --allow-empty flag:

git commit -m 'Initial commit' --allow-empty

Push this up to GitHub:

git push

You cannot have any files in the repository. It must be empty.

You should now have an empty GitHub repository that looks like this:

2. Get your public key and connect to your branch​

As an admin, login to Retool and go to Settings > Advanced. Toward the bottom of the page, there is a section for Git Syncing URL and Branch.

Enter your GitHub URL and branch name and click "Save". Make sure you enter the SSH URL, not the HTTPS URL. The SSH URL should mirror this format:

git@github.com:USERNAME/REPO_NAME.git

Your Retool instance provides a public key to authorize Git syncing. Click the blue link to Download Retool's public key. Open the retool.pub file and copy the entire key to your clipboard.

3. Configure the Deploy Key in GitHub​

Navigate back to your GitHub repository and click on the Settings tab, then click Deploy Keys on the left sidebar. Click Add Deploy Key, give it a title, and paste the Retool public key from your clipboard.

Make sure you check the box for Allow Write Access so that Retool can commit to this repository.

Add Retool's public key to your Git repository. Make sure you grant write access.

Refer to the rotate SSH keys guide for instructions on key rotation, then configure the deploy key again.

4. Test that syncing works​

Create a new app or make a change to an existing app in Retool. After about 10 seconds, you should should see the changes syncing to your repository.

Configure a read-only Retool instance​

A common setup is to have your production Retool instance be read-only. This is required to sync apps from GitHub to your Retool instance. By configuring this feature, you will disable making any changes to production Retool apps from the browser and force all changes to be read from the Git repository.

Before configuring a read-only instance of Retool, make sure you've already configured a separate instance to push changes to an existing repository.

When you set up a Retool instance to be read-only from a branch of a GitHub repository, the Git syncing process will replace all existing applications in the Retool Postgres database with those found in the repository. That means you will lose any existing apps that are not already in the repository.

1. Lock the instance from in-app changes​

To lock your instance from in-app changes, define the following environment variable in your docker.env file:

VERSION_CONTROL_LOCKED=true

2. Create a new branch in your GitHub repository​

From the command line or GitHub UI, create a new branch for this instance to follow. Give it a name that makes sense for this instance (e.g. staging for the staging instance).

3. Get your public key and connect to your branch​

As an admin, login to Retool and go to Settings > Advanced. Toward the bottom of the page, there is a section for Git Syncing URL and Branch.

Enter your GitHub URL and branch name and click "Save". Make sure you enter the SSH URL, not the HTTPS URL. The SSH URL should mirror this format:

git@github.com:USERNAME/REPO_NAME.git

Your Retool instance provides a public key to authorize Git syncing. Click the blue link to Download Retool's public key. Open the retool.pub file and copy the entire key to your clipboard.

4. Configure the Deploy Key in GitHub​

Navigate back to your GitHub repository and click on the Settings tab, then click Deploy Keys on the left sidebar. Click Add Deploy Key, give it a title, and paste the Retool public key from your clipboard.

Adding the deploy key of the read-only instance to the repository. Leave the option for "Allow write access" unchecked.

Write access is not required as the instance is read-only. Enabling this option may cause unexpected behavior.

Refer to the rotate SSH keys guide for instructions on key rotation, then configure the deploy key again.

5. Test that syncing works​

Wait a few moments and then refresh the Retool page in the browser. You should now see the same apps from your GitHub repository appear in Retool.

Retool application DSL

Retool encodes data for each Retool application internally using an extension of JSON. While effective, it is a format that makes it difficult to visualize change history, so instead of directly storing this data in version control, Retool reformats the data into a YAML file.

A simple page that with a table showing data from a query might be represented as follows:

Example Retool DSL
version: 2.8.1
components:
  - id: table1
    position:
      top: 1
      right: 1
      width: 8
      height: 5
    template:
      data: "{{ query1.data }}"
      selectedIndex: ''
      columns:
        - id
        - name
        - salary
      columnWidths:
        - 10
        - 100
        - 50
      columnColors:
        - white
        - white
        - "{{ self > 60 : 'green' : 'red' }}"
      pageSize: 10
      alwaysShowPaginator: true
      onRowSelect: ''
      serverPaginated: false
      totalRowCount: ''
      paginationOffset: 0
      sort: null
      sortedColumn: ''
      sortedDesc: false
      allowMultiRowSelect: false
queries:
  - id: query1
    template:
      query: "select * from users"
      runWhenPageLoads: false
      runWhenModelUpdates: true
      requireConfirmation: false
      confirmationMessage: ""
      queryDisabled: "",
      triggersOnSuccess: []
      triggersOnFailure: []
      privateParams: []
      queryRefreshTime: ''
      queryThrottleTime: '750'
      queryTimeout: '10000'
      showSuccessToaster: true,
      successMessage: ''

Every save in Retool automatically triggers a new commit message in the repository.