Setting up

Protected applications are powered by Git and the GitHub API. You’ll need to create and configure a GitHub App for your Retool instance to commit, push and pull changes from your Git repository.

Create a Git repository

Create a new Git repository with a for your protected applications on GitHub.


Do not use an existing Git repository

Protected applications will not work with an existing Git Syncing repository

Create a GitHub App

GitHub has a guide for creating a GitHub App, but the screenshots and content are a bit out of date.

  1. Open the Create GitHub App form for your GitHub organization.
  2. We suggest naming your app “{My-Company}’s Retool Deployment” or “{My-Company}’s Retool Instance”, but feel free to pick your own name.
  3. The homepage URL is required, but it can be any valid URL as it won’t be used by Retool.
  4. Keep the “Expire user authorization tokens” option checked. Leave the “Request user authorization (OAuth) during installation” option unchecked.
User authorization expiration settingsUser authorization expiration settings

User authorization expiration settings

  1. In the Webhook section, uncheck the “Active” option.
Webhook settingsWebhook settings

Webhook settings

  1. The only permission the application needs is “Read & write” to “Contents”
Contents access: Read & writeContents access: Read & write

Contents access: Read & write

  1. Make sure the application can only be installed in your organization
Limit installation accountsLimit installation accounts

Limit installation accounts

Installing the application

Once your application has been created, is should be listed in the GitHub Apps section of Developer Settings (

  1. Click Edit next to your app to see its settings
  2. Click on Install App
  3. Click the Install button next to your organization
  4. Pick “Only select repositories” and choose the repository created in the first section
Installation screenInstallation screen

Installation screen

  1. You’ll be redirected to the installation page. The number at the end of the URL is the installation ID. Save this for later.

Find the App ID

  1. On the same page as in the previous section, click on App settings link underneath the application name. Find the App ID. Save this for later.
Installation: About pageInstallation: About page

Installation: About page

Generate a private key

  1. On the app settings page, scroll down to the Private Keys section
  2. Click "Generate a private key"
  3. Download and save the .pem key. The filename should be match {github-app-name}.YYYY-MM-DD.private-key.pem.
  4. Base64 encode the contents of the file and save for later.
base64 path/to/{github-app-name}.YYYY-MM-DD.private-key.pem > github-private-key.txt

Configure Retool

Retool needs three pieces of information to authenticate as your newly created application. You should already have these if you followed the previous steps.

    • Found in the application settings
    • Created when the application is installed
    • The base64-encoded value of the newly created private key, saved in github-private-key.txt

Set these as environment variables and restart the containers.

Configure the GitHub repository

Next, go the “Advanced” tab in organization settings. The "Protected Applications Settings" section should now be editable.

Fill this out using the repository you created at the beginning of this guide. The two URL fields can be left blank unless you're using GitHub Enterprise.

Ensure that "Enable protected apps syncing on this instance" is checked, and click “Save”!

Note: If you are using GitHub Enterprise, the GitHub Enterprise API URL is customizable, so please ask your admin. However, the default value will look something like this:


Internal Server Error

If the system time on the machine that Retool is running on is out of sync or has "drifted," Retool can have trouble authenticating with the Github API.

If you're getting 500 Internal Server Error when making a commit on a branch, or seeing errors like 'Issued at' claim ('iat') must be an Integer representing the time that the assertion was issued in Retool API server logs, check that the system time where the Retool image is running is accurate. Restarting the system can be a solution to this error.

What’s Next

You’re now ready to protect your first application and start making changes via branches. Please watch the following short videos on how to protect and edit your application.

Did this page help you?