Set up Source Control with GitLab

Learn how to implement Source Control for Self-hosted Retool with GitLab.

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.

Setup instructions

  1. If you were previously using Git Syncing, disable it:
    2. Under Settings -> Advanced on Retool, delete the repo URL and branch name from your Git Syncing configuration.
  2. 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:
    1. Set the correct group under the Project URL dropdown.
    2. Select the Initialize repository with a README checkbox.

  1. Create an access token for your new project. To set up a project access token:
    1. Follow GitLab's Project access token documentation.
    2. While creating the token, set the following scopes: api, read_api, read_repository, write_repository. The role should be set to either maintainer or developer.

  1. Set the following environment variables on your Retool instances:

    Variable nameDescriptionExample value
    GITLAB_URLYour base GitLab URL. For GitLab Cloud, this is always For GitLab self-managed, this is the URL where your instance is hosted.Cloud: Self-managed:
    GITLAB_PROJECT_ACCESS_TOKENRetool 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.
    GITLAB_PROJECT_IDEvery 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.
    GITLAB_MAIN_BRANCHThe default branch for your GitLab project.main
    GITLAB_ORGANIZATION_NAMEThe name of your GitLab organization. This can also be a username if the project is not part of an, username, engineering, etc.
    GITLAB_REPOSITORY_NAMEThe name of the GitLab projectretool-apps
    GITLAB_PROJECT_SLUGThe URL path to your GitLab projectretool/eng/retool-apps
    VERSION_CONTROL_LOCKEDWhen 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.false

Configure environment variables

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 is the URL for your GitLab project, then set one of the following
    • GITLAB_ORGANIZATION_NAME=retool-source and GITLAB_REPOSITORY_NAME=gitlab-retool-dev.
    • GITLAB_PROJECT_SLUG=retool-source/gitlab-retool-dev.
  • If is the URL for your GitLab project, then set one of the following
    • GITLAB_PROJECT_SLUG=username/retool-apps.
  • If you are using GitLab’s subgroups feature, your project URL might look something like, then set one of the following
    • GITLAB_ORGANIZATION_NAME=tryretool/sales and GITLAB_REPOSITORY_NAME=retool-apps.
    • GITLAB_PROJECT_SLUG=tryretool/sales/retool-apps.

Verify Gitlab settings

Retool v2.97 or greater

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:

Source control set up

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:

Set up GitLab

Retool v2.96 or earlier

Confirm that GitLab is correctly set up by protecting your first application.