# Step-by-step deployment guide

### 1. Which data is imported from GitLab?

The following GitLab entity types are imported:

* `Users`
* `Groups`
* `Projects`
* `Group Roles`
* `Project Roles`

**Group Roles** and **Project Roles** are synthetic entities generated by the connector. For every Group (or Project), one role entity is created per access level (e.g. `Guest`, `Developer`, `Maintainer`, `Owner`). Users are then linked to the role that matches their actual access level in that group or project. This lets Elimity model GitLab's permission structure as a standard identity graph.

The diagram below shows how the entity types relate to each other:

```mermaid
graph TD

User[User]
Group[Group]
Project[Project]
GroupRole[Group Role]
ProjectRole[Project Role]

User --> GroupRole
GroupRole --> Group

User --> ProjectRole
ProjectRole --> Project
```

The following attributes are imported per entity type:

**User**

| Attribute            | Description                                      |
| -------------------- | ------------------------------------------------ |
| `email`              | Primary or public email address                  |
| `username`           | GitLab username (login handle)                   |
| `external`           | Whether the user is flagged as external          |
| `is_admin`           | Whether the user has instance-level admin rights |
| `last_sign_in`       | Timestamp of the user's last sign-in             |
| `two_factor_enabled` | Whether two-factor authentication is enabled     |
| `created_at`         | Account creation date                            |

**Group**

| Attribute     | Description                                           |
| ------------- | ----------------------------------------------------- |
| `visibility`  | Group visibility (`private`, `internal`, or `public`) |
| `fullpath`    | Full path of the group within the GitLab namespace    |
| `description` | Group description                                     |

**Project**

| Attribute     | Description                                                  |
| ------------- | ------------------------------------------------------------ |
| `path`        | Full name including namespace (e.g. `my-group / my-project`) |
| `description` | Project description                                          |
| `visibility`  | Project visibility (`private`, `internal`, or `public`)      |

**Group Role / Project Role**

| Attribute         | Description                             |
| ----------------- | --------------------------------------- |
| `accesslevel`     | Numeric access level (e.g. `30`)        |
| `accesslevelname` | Human-readable label (e.g. `Developer`) |

### 2. Create a dedicated GitLab personal access token

We recommend creating a dedicated service account or using an existing admin account to generate **a personal access token (PAT)**. The connector needs admin-level access to list all users, groups and projects across the entire instance.

1. Sign in to your GitLab instance with an account that has **Admin** rights.
2. Open the user menu in the top-right corner and go to **Preferences**
3. Click **Access** in the left navbar and go to **Personal Access Tokens**.
4. Click **Add new token** and fill in (select **Legacy token**)
   * **Token name:** something descriptive, e.g. `elimity-insights-connector`
   * **Expiration date:** set an expiry that fits your rotation policy
   * **Scopes:** select `read_user`, `read_api` and `self_rotate`
5. Click **Generate token** and immediately copy the token value. GitLab only shows it once.

> **Tip:** Verify the token works before configuring it in Elimity. Run the following command and confirm you see your user profile returned:
>
> ```
> curl --header "PRIVATE-TOKEN: <your-token>" https://<your-gitlab-host>/api/v4/user
> ```
>
> The response should include `"is_admin": true`. If it does not, the connector will log a warning and some data may be missing.

### 3. Note down your GitLab base URL

The connector needs the root URL of your GitLab instance (without a trailing slash).

Examples:

* Self-managed instance: `https://gitlab.yourcompany.com`
* GitLab.com: `https://gitlab.com`

### 4. Configure the source in Elimity Insights

1. Go to **Sources** in the left navigation bar and click **Add Source**.
2. Search for **Custom** and click **Set Up**.
3. Click **Set Up** again and give the source a name (e.g. `GitLab`).
4. Select **Upload export file**, click **Continue** and upload the data model file: `gitlab-data-model.json`

{% file src="/files/YdhuHMWz22J0W0y0ba8L" %}

1. Open the **Config** tab and click **Edit**.
2. Set **Enable automatic imports via custom gateway** to `true` and fill in the Gateway URL: `https://gitlab-gateway-1027270379075.europe-west1.run.app`
3. Click **Add configuration value** and add the entries below.

| Key           | Type       | Where to find it                                  |
| ------------- | ---------- | ------------------------------------------------- |
| `baseUrl`     | `Text`     | See step 3 — the root URL of your GitLab instance |
| `accessToken` | `Password` | See step 2 — the personal access token            |

Click **Save and run** to launch your first import. Monitor progress in the **Logs** tab; the **Imports** tab shows the summary for each run.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.elimity.com/gitlab/step-by-step-deployment-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.