Source Control with GitLab requires Retool v2.87.11 or greater, and supports integrations with GitLab SaaS (cloud) and GitLab Self-managed. If you're using GitLab Cloud, you need to be on the GitLab Premium plan or above. Project access tokens are only supported on GitLab Premium or higher plans, and Retool uses these tokens to authenticate against the GitLab API to get read and write access to the GitLab project you set up to use with Retool.
- If you were previously using Git Syncing, disable it:
- Under Settings -> Advanced on Retool, delete the repo URL and branch name from your Git Syncing configuration.
- Create a new blank project on GitLab. This project repository will store the apps under Source Control from your Retool deployment. Ensure the following settings are correct when creating the project:
- Set the correct group under the Project URL dropdown.
- Select the Initialize repository with a README checkbox.
- Create an access token for your new project. To set up a project access token:
- Follow GitLab's Project access token documentation.
- While creating the token, set the following scopes:
api, read_api, read_repository, write_repository. The role should be set to either
Set the following environment variables on your Retool instances:
Variable name Description Example value
Your base GitLab URL. For GitLab Cloud, this is always https://gitlab.com. For GitLab self-managed, this is the URL where your instance is hosted. Cloud: https://gitlab.com Self-managed: https://gitlab.mycompany.com
Retool uses GitLab’s Project access tokens for authenticating against the GitLab API. Each token gives Retool read and write API access to a specific GitLab project.
See the setup instructions to learn how to generate an access token.
Every GitLab project has a numerical project ID. You can find this ID listed below the project's name on the project's homepage.
For example, the project ID for the GitLab project is 278964.
The default branch for your GitLab project. main
The name of your GitLab organization. This can also be a username if the project is not part of an organization. company, username, engineering, etc.
The name of the GitLab project retool-apps
The URL path to your GitLab project retool/eng/retool-apps
When set to
true, the instance becomes a "read-only" instance and users cannot create or edit apps. Available on Retool versions 2.91 and later.
Your Retool instance uses GitLab-specific environment variables to recreate the host URL for your GitLab project. You must provide values for either:
It is not necessary to provide all three.
- If https://gitlab.com/retool-source/gitlab-retool-dev is the URL for your GitLab project, then set one of the following
- If https://gitlab.com/username/retool-apps is the URL for your GitLab project, then set one of the following
- If you are using GitLab’s subgroups feature, your project URL might look something like https://gitlab.com/tryretool/sales/retool-apps, then set one of the following
To verify your Gitlab provider is correctly set up, navigate to the “Source Control” tab in organization settings. If the page looks like this, please verify your environment variables are correctly configured and restart your Retool instance:
If your environment variables are correctly configured, you should see the main status page.
You can verify your settings are correct by using the ‘Test config’ button here:
Confirm that GitLab is correctly set up by protecting your first application.
Updated 4 days ago