Git Syncing

Retool is a platform built for developers by developers, and because of this, we put a tremendous emphasis on ensuring that you’re not making concessions on software development lifecycle best practices. As you’re building and iterating on your Retool applications, you want to make sure that your end users are using production-ready apps. Our Git-syncing feature allows you to completely customize how Retool apps are developed and deployed.


Git syncing is an on prem feature only and is not available if you're using the cloud version of Retool. You can get in touch with sales to deploy on prem here.

Setting up the Retool Git syncing

1. Getting Retool's public key and connecting to your branch

Retool provides a public key to authorize git syncing. As an admin, login to Retool, go to Settings and then Advanced. At the bottom of the page, there will be a link to download Retool's public key. Download it and copy the entire key. Note you must be on version v2.41.13 or later of Retool.

On the same page, 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 be of the format
[email protected]:USERNAME/REPO_NAME.git

2. Configure the Deploy Key in GitHub

Log into your GitHub account and create a new repository for your Retool instance. Click on the Settings tab of that repository and then click Deploy Keys on the left sidebar. Click Add Deploy Key, give it a title, and paste the Retool public key. Make sure you check 'Allow Write Access'.

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

3. Create an empty Git repository

We'll need to initialize the repository as an empty repository. To do that, we can just create a new local directory and clone our repository, cd into it, and create an empty commit using the --allow-empty flag and push to our repository.

Note: you cannot have any files in the repository. It must be empty!

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

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

Now make an edit to an app on your Retool instance, give the Git Syncing about 10 seconds, and you should see the changes syncing to Git!

4. Configuring the instance to read from a Git repository

After steps 1-3 are completed, you can also configure Retool to pull changes from the Git repository instead of writing saves to the Git repository. To do that, simply define the following environment variable:


This will cause Retool to begin syncing apps from the Git repository to the main app. As part of this, it also disables making any changes to the main Retool app.

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:

version: 2.8.1
  - id: table1
      top: 1
      right: 1
      width: 8
      height: 5
      data: "{{ }}"
      selectedIndex: ''
        - id
        - name
        - salary
        - 10
        - 100
        - 50
        - white
        - white
        - "{{ self > 60 : 'green' : 'red' }}"
      pageSize: 10
      alwaysShowPaginator: true
      onRowSelect: ''
      serverPaginated: false
      totalRowCount: ''
      paginationOffset: 0
      sort: null
      sortedColumn: ''
      sortedDesc: false
      allowMultiRowSelect: false
  - id: query1
      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 will automatically trigger a new commit message in the repository

Integrations with Retool releases

By default, Retool automatically shows the most recent version of a page to users of the application. While helpful for debugging, it can be helpful to tag saves as a release and only show that version to users. When a release is created, Retool automatically pushes a tag to the Git repository as well.

Updated 2 months ago

What's Next

Check out some common git workflows for Retool app development

Retool git workflow

Git Syncing

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.