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:
    1. Set DISABLE_GIT_SYNCING=true and VERSION_CONTROL_LOCKED=false.
    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 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
    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.
    glpat-123xyzabc456
    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.
    1234
    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 organization.company, 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_LOCKEDFor Retool versions 2.91 and later, setting this environment variable prevents the instance from pushing changes to GitLab. Useful for creating a "read-only" production instance of Retool.true

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:

  • GITLAB_ORGANIZATION_NAME and GITLAB_REPOSITORY_NAME, or
  • GITLAB_PROJECT_SLUG only

It is not necessary to provide all three.

Examples

  • If https://gitlab.com/retool-source/gitlab-retool-dev 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 https://gitlab.com/username/retool-apps is the URL for your GitLab project, then set one of the following
    • GITLAB_ORGANIZATION_NAME=username and GITLAB_REPOSITORY_NAME=retool-apps.
    • GITLAB_PROJECT_SLUG=username/retool-apps.
  • 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
    • 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 upSource 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 GitLabSet up GitLab

Retool v2.96 or earlier

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


Did this page help you?