infisical/docs/integrations/app-connections/gitlab.mdx

---
title: "GitLab Connection"
description: "Learn how to configure a GitLab Connection for Infisical using OAuth or Access Token methods."
---

Infisical supports two methods for connecting to GitLab: **OAuth** and **Access Token**. Choose the method that best fits your setup and security requirements.

<Tabs>
  <Tab title="OAuth Method">
    The OAuth method provides secure authentication through GitLab's OAuth flow.

    <Accordion title="Self-Hosted Instance Setup">
      Using the GitLab Connection with OAuth on a self-hosted instance of Infisical requires configuring an OAuth application in GitLab and registering your instance with it.

      <Tip>If you're self-hosting Gitlab with custom certificates, you will have to configure your Infisical instance to trust these certificates. To learn how, please follow [this guide](../../self-hosting/guides/custom-certificates).</Tip>

      **Prerequisites:**
      - A GitLab account with existing projects
      - Self-hosted Infisical instance

      <Steps>
        <Step title="Create an OAuth application in GitLab">
          Navigate to your user Settings > Applications to create a new GitLab application.

          ![GitLab Dashboard](/images/app-connections/gitlab/gitlab-dashboard.png)
          ![GitLab Applications Settings](/images/app-connections/gitlab/gitlab-applications.png)


          Create the application. As part of the form, set the **Redirect URI** to `https://your-domain.com/organization/app-connections/gitlab/oauth/callback`.

            Depending on your use case, add one or more of the following scopes to your application:

            <Tabs>
                <Tab title="Secret Sync">
                    For Secret Syncs, your application will require the `api` scope:

                    ![GitLab New Application Form](/images/app-connections/gitlab/gitlab-create-application-top-secret-sync.png)
                    ![GitLab New Application Form](/images/app-connections/gitlab/gitlab-create-application-bottom-secret-sync.png)
                </Tab>
                <Tab title="Secret Scanning">
                    For Secret Scanning, your application will require the `api` and `read_repository` scopes:

                    ![GitLab New Application Form](/images/app-connections/gitlab/gitlab-create-application-top-secret-scanning.png)
                    ![GitLab New Application Form](/images/app-connections/gitlab/gitlab-create-application-bottom-secret-scanning.png)
                </Tab>
            </Tabs>

          <Tip>
            The domain you defined in the Redirect URI should be equivalent to the `SITE_URL` configured in your Infisical instance.
          </Tip>

          <Note>
            If you have a GitLab group, you can create an OAuth application under it in your group Settings > Applications.
          </Note>
        </Step>
        <Step title="Add your GitLab OAuth application credentials to Infisical">
          Obtain the **Application ID** and **Secret** for your GitLab OAuth application.

          ![GitLab Application Credentials](/images/app-connections/gitlab/gitlab-config-credentials.png)

          Back in your Infisical instance, add two new environment variables for the credentials of your GitLab OAuth application:

          - `INF_APP_CONNECTION_GITLAB_OAUTH_CLIENT_ID`: The **Application ID** of your GitLab OAuth application.
          - `INF_APP_CONNECTION_GITLAB_OAUTH_CLIENT_SECRET`: The **Secret** of your GitLab OAuth application.

          Once added, restart your Infisical instance and use the GitLab Connection.
        </Step>
      </Steps>
    </Accordion>

    ## Setup GitLab OAuth Connection in Infisical

    <Steps>
      <Step title="Navigate to App Connections">
        Navigate to the **App Connections** page in the desired project.
        ![App Connections Tab](/images/app-connections/general/add-connection.png)
      </Step>
      <Step title="Add Connection">
        Select the **GitLab Connection** option from the connection options modal.
        ![Select GitLab Connection](/images/app-connections/gitlab/select-gitlab-connection.png)
      </Step>
      <Step title="Choose OAuth Method">
        Select the **OAuth** method and click **Connect to GitLab**.

        ![Connect via GitLab OAuth](/images/app-connections/gitlab/create-gitlab-oauth-connection.png)
      </Step>
      <Step title="Grant Access">
        You will be redirected to GitLab to grant Infisical access to your GitLab account. Once granted, you will be redirected back to Infisical's App Connections page.
        ![GitLab Authorization](/images/app-connections/gitlab/gitlab-authorization-page.png)
      </Step>
      <Step title="Connection Created">
        Your **GitLab Connection** is now available for use.
        ![GitLab OAuth Connection](/images/app-connections/gitlab/gitlab-oauth-connection.png)
      </Step>
    </Steps>

  </Tab>

  <Tab title="Access Token Method">
    The Access Token method uses a GitLab access token for authentication, providing a straightforward setup process.

    ## Generate GitLab Access Token

    <Tabs>
      <Tab title="Personal Access Token">
        Personal access tokens provide access to your GitLab account and all projects you have access to.

        <Steps>
          <Step title="Navigate to Access Tokens">
            Log in to your GitLab account and navigate to User Settings > Access tokens. Click **Add new token** to create a new personal access token.

            ![GitLab Personal Access Tokens](/images/app-connections/gitlab/gitlab-add-access-token.png)
          </Step>
          <Step title="Configure Token">
              Fill in the token details:
              - **Token name**: A descriptive name for the token (e.g., "connection-token")
              - **Expiration date**: Set an appropriate expiration date
              - **Select scopes**: Depending on your use case, add one or more of the following scopes:

            <Tabs>
              <Tab title="Secret Sync">
                  For Secret Syncs, your token will require the `api` scope:

                  ![GitLab Personal Token Form](/images/app-connections/gitlab/gitlab-personal-access-token-form-secret-sync.png)
              </Tab>
                <Tab title="Secret Scanning">
                    For Secret Scanning, your token will require the `api` and `read_repository` scopes:

                    ![GitLab Personal Token Form](/images/app-connections/gitlab/gitlab-personal-access-token-form-secret-scanning.png)
                </Tab>
            </Tabs>

            <Info>
              Personal Access Token connections require manual token rotation when your GitLab access token expires or is regenerated. Monitor your connection status and update the token as needed.
            </Info>
          </Step>
          <Step title="Copy Token">
            Copy the generated token immediately as it won't be shown again.

            ![GitLab Personal Token Created](/images/app-connections/gitlab/gitlab-copy-token.png)

            <Warning>
              Keep your access token secure and do not share it. Anyone with access to this token can access your GitLab account and projects.
            </Warning>
          </Step>
        </Steps>
      </Tab>

      <Tab title="Project Access Token">
        Project access tokens provide access to a specific GitLab project, offering more granular control.

        <Steps>
          <Step title="Navigate to Project Settings">
            Go to your GitLab project and navigate to Settings > Access Tokens. Click **Add new token** to create a new project access token.

            ![GitLab Project Access Tokens](/images/app-connections/gitlab/gitlab-project-access-token-list.png)
          </Step>
          <Step title="Configure Token">
              Fill in the token details:
              - **Token name**: A descriptive name for the token
              - **Expiration date**: Set an appropriate expiration date
              - **Select role and scopes**: Depending on your use case, add the required role and one or more of the following scopes:

            <Tabs>
                <Tab title="Secret Sync">
                  For Secret Syncs, your token will require the `api` scope and at least the **Owner** role:

                  ![GitLab Create Project Token](/images/app-connections/gitlab/gitlab-project-access-token-form-secret-sync.png)
                </Tab>
                <Tab title="Secret Scanning">
                    For Secret Scanning, your token will require the `api` and `read_repository` scopes and the **Maintainer** role:

                    ![GitLab Create Project Token](/images/app-connections/gitlab/gitlab-project-access-token-form-secret-scanning.png)
                </Tab>
            </Tabs>

            <Info>
              Project Access Token connections require manual token rotation when your GitLab access token expires or is regenerated. Monitor your connection status and update the token as needed.
            </Info>
          </Step>
          <Step title="Copy Token">
            Copy the generated token immediately as it won't be shown again.

            ![GitLab Project Token Form](/images/app-connections/gitlab/gitlab-project-access-token-created.png)

            <Warning>
              Keep your access token secure and do not share it. Anyone with access to this token can access your GitLab account and projects.
            </Warning>
          </Step>
        </Steps>
      </Tab>

      <Tab title="Group Access Token">
        Group access tokens provide access to all projects within a GitLab group, offering group-level control.

        <Steps>
          <Step title="Navigate to Group Settings">
            Go to your GitLab group and navigate to Settings > Access Tokens. Click **Add new token** to create a new group access token.
            ![GitLab Group Access Tokens](/images/app-connections/gitlab/gitlab-group-access-token-list.png)
          </Step>
          <Step title="Configure Token">
              Fill in the token details:
              - **Token name**: A descriptive name for the token
              - **Expiration date**: Set an appropriate expiration date
              - **Select role and scopes**: Depending on your use case, add the required role and one or more of the following scopes:

            <Tabs>
                <Tab title="Secret Sync">
                  For Secret Syncs, the required role depends on your sync destination:
                  - **Project variables**: Requires **Maintainer** role or higher
                  - **Group variables**: Requires **Owner** role

                  Your token will require the `api` scope.

                  ![GitLab Create Group Token](/images/app-connections/gitlab/gitlab-group-access-token-form-secret-sync.png)

                  Click **Create group access token** to create the token.

                  <Note>
                    Use the **Owner** role if you need to sync to group-level variables. The **Maintainer** role is sufficient only for project-level variables.
                  </Note>
                </Tab>
                <Tab title="Secret Scanning">
                     To set up Secret Scanning, the required permissions depend on the data source level:
                      - **Project-level data source:** Requires **Maintainer** role or higher
                      - **Group-level data source:** Requires **Owner** role

                    Your token will require the `api` scope.

                  ![GitLab Create Group Token](/images/app-connections/gitlab/gitlab-group-access-token-form-secret-sync.png)

                  Click **Create group access token** to create the token.
              </Tab>
          </Tabs>

          <Info>
            Group Access Token connections require manual token rotation when your GitLab access token expires or is regenerated. Monitor your connection status and update the token as needed.
          </Info>
        </Step>
        <Step title="Copy Token">
          Copy the generated token immediately as it won't be shown again.
          ![GitLab Group Token Created](/images/app-connections/gitlab/gitlab-group-access-token-created.png)
          <Warning>
            Keep your access token secure and do not share it. Anyone with access to this token can access all projects within your GitLab group.
          </Warning>
        </Step>
      </Steps>

    </Tab>

</Tabs>

## Setup GitLab Access Token Connection in Infisical

  <Steps>
  <Step title="Navigate to App Connections">
    Navigate to the **App Connections** page in the desired project.
    ![App Connections Tab](/images/app-connections/general/add-connection.png)
  </Step>
  <Step title="Add Connection">
    Select the **GitLab Connection** option from the connection options modal.
    ![Select GitLab Connection](/images/app-connections/gitlab/select-gitlab-connection.png)
  </Step>
  <Step title="Configure Access Token">
    Select the **Access Token** method, paste your GitLab access token in the provided field, and select the appropriate token type.

      ![Configure Access Token](/images/app-connections/gitlab/create-gitlab-access-token-connection.png)

      Click **Connect** to establish the connection.

    </Step>

  <Step title="Connection Created">
    Your **GitLab Connection** is now available for use.
    ![GitLab Access Token Connection](/images/app-connections/gitlab/gitlab-access-token-connection.png)
  </Step>
</Steps>

  </Tab>
</Tabs>