Documentation

Welcome to Retool! We're a fast way to build custom internal software.

You'll find the 5 minute demo, quickstart guide, and documentation for each of our connectors and components here. If you've got any questions -- chat with us on the bottom right!

Get Started    Guides

Git Syncing

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
git@github.com: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 repo 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 repo and make sure you grant write access.

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

3. Create an empty repository

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

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

git clone https://github.com/GITHUB_USERNAME/REPO_NAME.git
cd REPO_NAME
git commit -m 'Initial commit' --allow-empty
git push

You should now have an empty GitHub repo 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 repo

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

VERSION_CONTROL_LOCKED=true

This will cause Retool to begin syncing apps from the git repo 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
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 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 repo as well.

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.