Skip to main content

Configure Source Control with GitLab

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

Source Control Availability
CloudGenerally Available
Self-hosted Edge 3.33 or laterGenerally Available
Self-hosted Stable 3.33 or laterGenerally Available

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.

Prerequisites​

Self-hosted instances 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.

Ensure your GitLab domain contains an IPv6 (AAAA) DNS record to prevent server errors when Retool attempts to connect to your GitLab instance.

You can confirm whether you have IPv6 configured by running:

dig <domain name> AAAA

If the output of the command is ANSWER: 0, then the IPv6 DNS record is missing.

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

SettingDescriptionExample
GitLab URLYour base GitLab URL. On GitLab Cloud, this is always https://gitlab.com. On GitLab self-managed, this is the URL where your instance is hosted.https://gitlab.mycompany.com
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 organization.company, username, engineering, etc.
GitLab repositoryThe name of the GitLab project.retool-apps
Configure GitLab settings on Retool
Configure GitLab settings on Retool

Secure credential management​

The Project access token field supports embedded expressions for secure credential management.

This feature is currently rolling to cloud instances and will be available in subsequent edge and stable releases. Toggle the Template variables in Source Control config feature flag in Settings > Beta to enable this feature.

  • You can reference configuration variables: 
    {{ environment.variables.MY_KEY_OR_TOKEN }}
  • On self-hosted instances, you can also reference secrets from secrets managers: 
    {{ secrets.MY_SECRET.KEY }}

The UI includes autocomplete and validation to help you use embedded expressions correctly.

3. Verify GitLab settings​

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