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. Providing Retool with git credentials

Retool currently supports authentication only through a private key. To do that, you will need to place a public - private key pair in the ./keys directory in the retool-onpremise repo.

cd ./keys
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

Then, give the public key (id_rsa.pub) to your git repo as an accepted public key.

2. Specifying the remote git repo url and branch

As an admin, login to Retool, go to Settings and then Advanced. At the bottom of the page, there will be a form where you can provide Retool with a git repo url and git branch.

3. Verifying it works

Retool should now begin to sync all the apps and history to the git repo as .yml files. To verify that it's working you can examine the logs of the Retool docker container. In on-premise instances where it is set up with docker-compose you can use the following command:

sudo docker-compose logs -f api

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.