docs/integrations/app-connections/gitlab.mdx
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.<Info>
Oauth Method is only supported in Self-Hosted mode.
</Info>
<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.
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:
</Tab>
<Tab title="Secret Scanning">
For Secret Scanning, your application will require the `api` and `read_repository` scopes:
</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.
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 **Integrations** tab in the desired project, then select **App Connections**.
</Step>
<Step title="Add Connection">
Select the **GitLab Connection** option from the connection options modal.
</Step>
<Step title="Choose OAuth Method">
Select the **OAuth** method and click **Connect to GitLab**.
</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.
</Step>
<Step title="Connection Created">
Your **GitLab Connection** is now available for use.
</Step>
</Steps>
## 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.
</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:
</Tab>
<Tab title="Secret Scanning">
For Secret Scanning, your token will require the `api` and `read_repository` scopes:
</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.
<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.
</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:
</Tab>
<Tab title="Secret Scanning">
For Secret Scanning, your token will require the `api` and `read_repository` scopes and the **Maintainer** role:
</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.
<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.
</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.
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.
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.
<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>
Click **Connect** to establish the connection.
</Step>