Configure Source Control with GitLab

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

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.

note

GitLab may enforce rate limits when Source Control is used across many Spaces.

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.

Configure settings in Retool

Configure the GitLab repository settings.

note

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.

Setting	Description	Example
GitLab URL	Your 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 token	The GitLab project access tokens to authenticate to the GitLab API.	glpat-123xyzabc456
GitLab project ID	The numerical project ID for your GitLab project. Find this ID listed below the project's name on the project's homepage.	278964
GitLab branch	The default branch for your GitLab project.	main
GitLab organization	The name of your GitLab organization. This can be a username if the project is not part of an organization.	company, username, engineering, etc.
GitLab repository	The name of the GitLab project.	retool-apps

Configure GitLab settings on Retool

Secure credential management

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

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.

Verify GitLab settings

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.

Save your settings

Click Save and deploy to save your settings.