Set up Source Control with GitHub

🚧

Source Control is only available to Enterprise users running Self-hosted Retool. You can book a demo with our Sales team to learn more about running Retool on-premise.

Source Control is 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 README.md and main branch for your applications under Source Control in GitHub.

❗️

Do not use an existing Git repository

Source Control 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.

5. In the Webhook section, uncheck the “Active” option.

6. Grant the application the following permissions:

• Read & write to Contents
• Read & write to Pull requests

7. Make sure the application can only be installed in your organization

Install the application

Once your application has been created, is should be listed in the GitHub Apps section of Developer Settings (https://github.com/settings/apps).

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

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

   https://github.com/settings/installations/:installation_id

Find the App Owner and ID

1. On the same page as in the previous section, click on App settings link underneath the application name. Find the App Owner and ID. Save them for later.

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 some information to authenticate as your newly created application. You should already have these if you followed the previous steps.

• GITHUB_APP_ID
  • Found in the application settings
  • Example: GITHUB_APP_ID=12345678
• GITHUB_APP_INSTALLATION_ID
  • Created when the application is installed
    • • Example: GITHUB_APP_INSTALLATION_ID=123456
• GITHUB_APP_PRIVATE_KEY
  • The base64-encoded value of the newly created private key, saved in github-private-key.txt
  • If you are using a Kubernetes Secret, you must base64 encode this value twice.

Users of self-hosted Retool v2.91 or above can optionally prevent the instance from pushing changes to GitHub. To lock version control, set the VERSION_CONTROL_LOCKED environment variable to true. This is useful for creating a "read-only" production instance of Retool.

Set these as environment variables and restart the containers.

Configure the GitHub repository

GitHub repository configuration for Self-hosted Retool v2.97 and later is slightly different than earlier versions.

• Retool v2.97 and later
• Retool v2.96 and earlier

Retool v2.97 and later

First, go to the Source Control tab in organization settings to configure the SCM provider.

Next, click Set up GitHub and enter the required settings for the repository you created at the beginning of this guide. Refer to the settings fields section for details about these settings.

Retool v2.96 and earlier

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

Enter the required settings for the repository you created at the beginning of this guide. Refer to the settings fields section for details about these settings.

Source control settings fields

Troubleshooting

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.

Cookies must be enabled to use GitHub

This error occurs when the GitHub Enterprise API URL provided is not an API route. Check the URL provided and confirm that it is a GitHub API route.

Unable to access GitHub

If your Retool instance is behind a firewall and cannot access the GitHub API, add api.github.com to your allowlist to enable outbound requests.