Skip to main content

Configure Source Control with GitLab

Learn how to set up Source Control with GitLab for self-hosted Retool.

Available on:Enterprise plan

You can use Source Control with GitLab to manage changes using pull requests. You create a repository for Source Control to use, then configure a GitLab project for your Retool instance that commits, pushes, and pulls changes.

Source Control requires the use of GitLab project access tokens. See GitLab's documentation to verify you have access to these tokens.


Self-hosted Retool deployments that currently use Git Syncing to sync with GitLab must disable this feature before switching to Source Control. To disable:

  • Set DISABLE_GIT_SYNCING=true and VERSION_CONTROL_LOCKED=false in the docker.env file.
  • Navigate to Settings > Advanced, then Remove the GitLab repository URL and branch name from your Git Syncing configuration.

1. Create a GitLab project

Create a new project on GitLab. This project repository stores the apps under Source Control from your Retool deployment. Use the following settings:

  • Set the correct group under the Project URL dropdown.
  • Select the Initialize repository with a README checkbox.

Next, follow GitLab's Project access token documentation to create an access token. Set the following scopes for the token:

  • api
  • read_api
  • read_repository
  • write_repository.

Set the role to maintainer or developer.

2. Configure settings in Retool

Configure the GitLab repository settings.

Go to the Source Control settings, and select Set up GitLab. Enter the following settings.

GitLab URLYour base GitLab URL. On GitLab Cloud, this is always On GitLab self-managed, this is the URL where your instance is hosted.
Project access tokenThe GitLab project access tokens to authenticate to the GitLab API.glpat-123xyzabc456
GitLab project IDThe numerical project ID for your GitLab project. Find this ID listed below the project's name on the project's homepage.278964
GitLab branchThe default branch for your GitLab project.main
GitLab organizationThe name of your GitLab organization. This can be a username if the project is not part of an, username, engineering, etc.
GitLab repositoryThe name of the GitLab project.retool-apps

Configure GitLab settings on Retool

3. Verify GitLab settings

On self-hosted Retool versions 2.97 and later, go to the Source Control settings page to verify your GitLab project is correctly configured. If you still see the Set up GitLab option, confirm your environment variables are set.

To confirm Retool can connect to your GitLab project, select Test connection.

On self-hosted Retool versions 2.96 and earlier, confirm GitLab is correctly set up by protecting your first application.

4. Save your settings

Click Save and deploy to save your settings.