## Introduction

GitLab is a web based Git repository manager. This guide walks you through the steps to gather the necessary information and configure your GitLab instance or group for the purpose of creating an integration with Synqly's Application Security connector.

## Prerequisites

Before you begin, ensure that you have:

- Access to the web interface of a GitLab instance
- Access to either a GitLab instance administrator or an account with the Owner role (Recommended)


## Required Token Scopes

| Operation | GitLab Token Scopes |
|  --- | --- |
| Query Applications | read_api |
| Query Application Findings | read_api |
| Query findings across all applications | read_api |
| Get Application Finding Details | read_api |


## Generating an API Access Token

GitLab currently supports three methods of creating a new API access token. **The recommended method is by using a service account** but service accounts are not available to users of a GitLab Free instance. If you are using a GitLab Free instance, it is recommended to use a group access token instead.

### 1. Navigation

To begin generating a new GitLab API access token, log into your GitLab instance's web interface and take note of the url. Next select a method of creating a new API access token below and follow the steps to reach the new API access token creation screen. Once there, proceed to the next step titled [2. Creating The Access Token](#2.-creating-the-access-token).

Service Account
**Creating a new instance wide service account**

1. Select **Admin** from the sidebar on the left
2. Select **Settings > Service accounts**
3. Select **Add service account** and fill out the fields to create a new instance wide service account
4. Select **Manage access tokens** from the vertical ellipsis to the right of the new service account. You are now on the new API access token creation screen, proceed to the next step titled [2. Creating The Access Token](#2.-creating-the-access-token)


**Creating a new group service account**

1. Navigate to the group in which you would like to create the service account
2. Select **Settings > Service accounts**
3. Select **Add service account** and fill out the fields to create a new group service account
4. Select **Manage access tokens** from the vertical ellipsis to the right of the new service account. You are now on the new API access token creation screen, proceed to the next step titled [2. Creating The Access Token](#2.-creating-the-access-token)


For more information on service accounts see the [GitLab service accounts docs page](https://docs.gitlab.com/user/profile/service_accounts/)

Group Access Token
1. Navigate to the group in which you would like to create the access token for
2. Select **Settings > Access tokens** from the left sidebar
3. Select **Add new token** in the section titled *Active group access tokens*. You are now on the new API access token creation screen, proceed to the next step titled [2. Creating The Access Token](#2.-creating-the-access-token)


For more information on group access tokens see the [GitLab group access tokens docs page](https://docs.gitlab.com/user/group/settings/group_access_tokens/)

Personal Access Token
1. Select your avatar from the sidebar on the left
2. Select **Edit profile**
3. Select **Access tokens** from the sidebar on the left
4. Select **Add new token**. You are now on the new API access token creation screen, proceed to the next step titled [2. Creating The Access Token](#2.-creating-the-access-token)


For more information on personal access tokens see the [GitLab Personal access tokens docs page](https://docs.gitlab.com/user/profile/personal_access_tokens/)

### 2. Creating the API Access Token

Once on the new API access token creation screen, fill out the token name field, optional description field, and expiration date field. Under the *Select scopes* header, check the box next to each of the required scopes. The required scopes can be found above under the section titled [Required Token Scopes](#required-token-scopes). Next select **Create token**. Finally, take note of the newly generated API access token. The URL and API access token will each be used when creating a new Synqly GitLab integration.

## Configuring the Integration

To configure a new GitLab integration in the Synqly system, provide each of the values as defined below:

| Integration Parameter | Description |
|  --- | --- |
| Secret | This is the API access token generated from executing the steps above |
| Base URL | The URL used to access the GitLab instance's web interface |