Setting Up GitLab

Requirements

  1. This feature requires Retool v2.87.11 or greater.
  2. This feature supports integrations with GitLab 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 name

Description

Example value

GITLAB_URL

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

GITLAB_PROJECT_ACCESS_TOKEN

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.

glpat-123xyzabc456

GITLAB_PROJECT_ID

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.

1234

GITLAB_MAIN_BRANCH

The default branch for your GitLab project.

main

GITLAB_ORGANIZATION_NAME

See below for more information.

company, username, engineering, etc.

GITLAB_REPOSITORY_NAME

See below for more information.

retool-apps

GITLAB_PROJECT_SLUG

See below for more information.

retool/eng/retool-apps

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

Setting the GITLAB_ORGANIZATION_NAME, GITLAB_REPOSITORY_NAME and GITLAB_PROJECT_SLUG environment variables

You only need to set one of the following two sets environment variables

  • GITLAB_ORGANIZATION_NAME, GITLAB_REPOSITORY_NAME
  • GITLAB_PROJECT_SLUG

Either one of the above two sets along with GITLAB_URL variables are used to recreate the host URL for your GitLab project.

For example:

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

Did this page help you?