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 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. The only permission the application needs is “Read & write” to “Contents”

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

Installing 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 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.

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.

• GITHUB_APP_ID
  • Found in the application settings
• GITHUB_APP_INSTALLATION_ID
  • Created when the application is installed
• 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.

Set these as environment variables and restart the containers.

Configure the GitHub repository

Next, go the “Advanced” tab in organization settings. The "Source Control 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. 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:

https://github.yourcompany.com/api/v3

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.