# GitLab

This integration discovers Users, Groups, and Projects for GitLab software development platform, along with authorization data for each group and projects. The integration supports self-hosted and SaaS GitLab deployments.

The GitLab integration requires a read-only access token for authentication, and will discover all groups, sub-groups, and projects the token can access. For self-hosted (non-SaaS) environments, you can optionally discover all groups and additional user information by providing an admin token.

See [Notes and Supported Entities](#notes-and-supported-entities) for more information.

### Setup

#### Generate a GitLab access token

1. Generate a [GitLab access token](https://docs.gitlab.com/ee/security/token_overview.html) under GitLab *Edit profile* > *Access Tokens*.
   * For self-hosted, we recommend generating a *personal access token for an Admin-level user* to enable full discovery.
   * For GitLab SaaS, a *group* token will typically be most appropriate. Personal access tokens for a group Owner can also be used.
   * Assign the access token `read_api` access only.
   * Assign the token a name and expiration date.
   * Save the generated token and use it to configure the integration.

#### Add the integration to Veza

To enable the integration:

1. Browse to the Veza platform and log in.
2. Go to **Integrations**.
3. Click **Create Integration**. Select **GitLab** as the integration to add.
4. Complete the required fields:
   * **Insight Point**: By default, integrations run on the Veza SaaS platform. Optionally, you can make an internal connection to GitLab with a deployed [Insight Point](/4yItIzMvkpAvMVFAamTf/integrations/connectivity/insight-point.md).
   * **Name**: Friendly name for the GitLab deployment.
   * **URL**: GitLab URL for the connection. Use `https://gitlab.com` for SaaS or specify URL for self-managed GitLab.
   * **Access Token**: Integration Access Token.
5. Click **Create Integration** to save and enable the configuration.

### Notes and supported entities

This connector creates the following entities to map applications and identities to permissions:

| GitLab          | Entity                        |
| --------------- | ----------------------------- |
| deployment      | GitLab Application            |
| users           | GitLab User                   |
| service account | GitLab User (Service Account) |
| GitLab admin    | GitLab Role                   |
| logged-in user  | GitLab Role                   |
| project         | GitLab Project Resource       |
| group           | GitLab Group                  |
| access token    | GitLab Access Credential      |

GitLab groups are represented both as a Group for User membership and as a Group Resource to show user's role in the group and associated permissions (such as Developer, Owner, Guest).

#### Attributes

| Entity  | Property        | Values                                              |
| ------- | --------------- | --------------------------------------------------- |
| User    | `email`         | Email address for user if available                 |
| User    | `bot`           | Boolean for bot users\*                             |
| User    | `gitlab_id`     | Unique GitLab user ID number                        |
| User    | `is_licensed`   | State of GitLab license usage                       |
| User    | `state`         | Account state `active`, `blocked`, `deactivated`    |
| User    | `is_active`     | True if account state is `active`                   |
| User    | `created_at`    | Time user account was created                       |
| User    | `last_login_at` | Time of last user login to GitLab\*                 |
| Project | `visibility`    | Project visibility, `private`, `internal`, `public` |
| Project | `gitlab_id`     | Unique GitLab project ID number                     |

#### Service accounts

GitLab service accounts are bot user accounts created at the group or instance level for automation purposes. Veza represents service accounts as GitLab Users with `user_type` set to `service_account`.

| Property            | Description                               |
| ------------------- | ----------------------------------------- |
| `bot`               | Always `true` for service accounts        |
| `unconfirmed_email` | Unconfirmed email address for the account |

Veza associates service accounts with the group where they originate, and discovers their personal access tokens as Access Credentials.

#### Access tokens

Veza represents GitLab access tokens (group access tokens, project access tokens, and service account personal access tokens) as Access Credentials. Each token shows its scope, access level, and the resource it grants access to.

| Property        | Description                                                                        |
| --------------- | ---------------------------------------------------------------------------------- |
| `token_id`      | Unique GitLab token ID                                                             |
| `owner_id`      | User ID of the token owner (for service account tokens)                            |
| `description`   | Token description                                                                  |
| `scopes`        | List of OAuth scopes granted to the token                                          |
| `access_level`  | GitLab access level (10=Guest, 20=Reporter, 30=Developer, 40=Maintainer, 50=Owner) |
| `resource_type` | Type of resource: `group`, `project`, or `service_account`                         |
| `resource_id`   | ID of the associated group or project                                              |
| `is_active`     | True if the token is active and not revoked                                        |
| `created_at`    | Token creation timestamp                                                           |
| `expires_at`    | Token expiration date                                                              |
| `last_used_at`  | Timestamp of last token usage                                                      |

Veza connects access tokens to their owning user (or service account) through the "Has Access Credentials" relationship.

#### SAML SSO visibility

For GitLab instances configured with SAML Single Sign-On, Veza discovers SAML identity information for users:

| Property        | Description                                                 |
| --------------- | ----------------------------------------------------------- |
| `saml_login`    | Boolean indicating whether the user has SAML SSO configured |
| `saml_login_id` | The user's SAML external ID from the identity provider      |

Use these attributes to identify users not authenticating through your corporate IdP (filter for `saml_login = false`) for compliance auditing, or to correlate GitLab users with IdP identities using the `saml_login_id`.

#### Automatic identity correlation

GitLab users are automatically correlated with identities from connected Identity Providers using email addresses. When a GitLab user's email matches an identity in an integrated IdP (such as Okta or Azure AD), Veza automatically creates the relationship, enabling end-to-end access visibility from IdP identities to GitLab resources without manual identity mapping configuration.

#### Limitations

* Attributes above marked with `*` are only available on self-hosted with an admin token
* Does not currently process external users


---

# 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.veza.com/4yItIzMvkpAvMVFAamTf/integrations/integrations/gitlab.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.