Configure Source Control with GitHub
Learn how to set up Source Control for Self-hosted Retool 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 self-hosting Retool.
You can use Source Control with GitHub to manage changes using pull requests. You create a repository for Source Control to use, then configure a GitHub App for your Retool instance that commits, pushes, and pulls changes.
1. Create a Git repository
Do not use an existing Git repository
Source Control does not work with an existing Git Syncing repository.
First, create a new repository for Source Control. Ensure it contains a README.md file and a main branch. Source Control uses this repository to store and track all changes.
2. Create and install a GitHub App
Create a GitHub App with the following settings. Refer to GitHub's guide for more information.
| Setting | Value |
|---|---|
| GitHub App name | The name of your GitHub App. |
| Homepage URL | The URL of your GitHub App. This field is unused by Retool. |
| Expire user authorization tokens | Unchecked |
| Request user authorization (OAuth) during installation | Unchecked |
| Webhook > Active | Unchecked |
| Permissions > Contents | Read and write |
| Permissions > Pull requests | Read and write |
| Where can this GitHub App be installed? | Only on this account |
Install the GitHub App
After you create your GitHub App, it should appear in the GitHub Apps section of your Developer Settings.
To install your GitHub App:
- Click Edit next to your app to see its settings.
- Click on Install App.
- Click the Install button next to your organization.
- Choose the Only select repositories option and select the repository created in the first section.
- 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
Save the app owner and app ID
On the same page, click on App settings underneath the GitHub App name. Save the Owned by and App ID fields for later.
3. Generate a private key
- Navigate to the Private Keys section and click Generate a private key.
- Download and save the
.pemkey. The filename should use the format{github-app-name}.YYYY-MM-DD.private-key.pem. - Base64-encode the contents of the file to use when configuring your instance. If you use Kubernetes Secrets, you must base64-encode this value twice.
base64 path/to/{github-app-name}.YYYY-MM-DD.private-key.pem > github-private-key.txt
4. Configure settings in Retool
Retool uses the information you've obtained to authenticate as your GitHub App. Set the following environment variables on the api and jobs-runner containers and then restart your containers.
| Setting | Description | Example |
|---|---|---|
GITHUB_APP_ID | The GitHub App ID. | GITHUB_APP_ID=12345678 |
GITHUB_APP_INSTALLATION_ID | The GitHub installation ID. This can be found at the end of the installation URL. | GITHUB_APP_INSTALLATION_ID=123456 |
GITHUB_APP_PRIVATE_KEY | The base64-encoded private key. | GITHUB_APP_PRIVATE_KEY=xxxxx |
Deployments using 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.
Configure the GitHub repository
The GitHub repository configuration location differs based on the version of Self-hosted Retool you use.
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 settings for the repository you created at the beginning of this guide. Refer to the GitHub settings section for details about these settings.
Retool v2.96 and earlier
Go the Advanced tab in organization settings. The Source Control Settings section should now be editable.
Enter the settings for the repository you created at the beginning of this guide. Refer to the GitHub settings section for details about these settings.
GitHub settings
| Setting | Required | Description |
|---|---|---|
| GitHub owner | Yes | The username or organization who owns the GitHub App, without the @ prefix, e.g., tryretool. |
| GitHub repository | Yes | The name of the repository you created to use with Retool. |
| GitHub branch | Yes | The default branch, e.g., main. |
| GitHub Enterprise URL | No | The domain used to access your self-hosted GitHub instance. |
| GitHub Enterprise API URL | No | The REST API route for your self-hosted GitHub instance. Defaults to https://[hostname]/api/v3. |
Troubleshooting
The following errors are issues common to Source Control with GitHub. Refer to the guide to resolve common Source Control issues to learn about other common errors.
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 see 500 Internal Server Error when making a commit on a branch, or see errors such as '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 solve this issue.
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.
Updated 7 days ago