# SailPoint GitLab Connector Documentation

> GitLab Connector Documentation

# Documentation

# Connecting SailPoint and GitLab

To connect SailPoint with GitLab, perform the following tasks:

## Adding the Source in SailPoint

To connect to SailPoint, perform the following steps. Once the connection is made, you can configure it to meet your company's needs.

1. Sign in to SailPoint.
2. Go to **Admin \> Connections \> Sources**.
3. Select **Create New**.
4. Search for the connector by entering the name in the search box, and then select **Actions**.
5. In the **Actions** dropdown list, select the setup method:

   - [**Express Setup**](<#configuring-a-source-using-express-setup>) - Quickly create a read-only connection to your target system by providing minimal configurations and authentication. On completion, aggregation is automatically started.

     > **Note**
     >
     > Express Setup supports Credential Providers. For information on supported credential providers and configuration, refer to [Credential Providers](<https://documentation.sailpoint.com/connectors/help/credential_providers.html>). For more information, contact your SailPoint Customer Service Manager.
   - [**Standard Setup**](<#configuring-a-source-using-standard-setup>) - Provide detailed basic configuration to create the source. Once the source is created, continue with source setup.

### Configuring a Source Using Express Setup

Express Setup minimizes the initial configuration process so you can quickly connect the application and immediately begin aggregating user account and entitlement data.

1. Review the directions and select **Start Express Setup**.
2. Review the pre-populated **Source Name**, **Source Owner**, and **Description**. To update, select **Edit**.

   > **Note**
   >
   > The source name must be unique. You can change these settings later in the source configuration.
3. Select **Virtual Appliance**. A virtual appliance is a Linux-based virtual machine that connects to your sources and apps using SailPoint APIs, connectors, and integrations. For more information about configuring and deploying virtual appliances, refer to [SailPoint Virtual Appliances](<https://documentation.sailpoint.com/saas/help/va/index.html>).
4. (Optional) If enabled for your organization, select the **Use a Credential Provider** checkbox to manage the source's authentication using a credential provider.

   > **Note**
   >
   > To add a Credential Provider in SailPoint, go to **Admin \> Connections \> Credential Providers**. For more information about credential providers, refer to [Credential Providers](<https://documentation.sailpoint.com/connectors/help/credential_providers.html>).
5. Configure the authentication to allow SailPoint to connect to the source. For more information, refer to the **Connection Settings** section.
6. Select **Finish**.

   After a successful test connection, the system creates your source and prompts you to run an aggregation.

   - If you want to aggregate now, select **Aggregate**.

     - To see the latest account aggregation history, go to **Account Management \> Account Aggregation**.
     - To see the list of aggregated source accounts, go to **Account Management \> Accounts**.
   - If you want to aggregate later, select **Exit**. This returns you to the **Sources** page. Your new source is listed, but contains no accounts or aggregation history yet.

### Configuring a Source Using Standard Setup

Use Standard Setup to configure the connector for full feature support.

1. In the **Source Name** field, enter a unique and descriptive name for your source. Source names cannot exceed 128 characters.
2. In the **Description** field, provide additional details about the source to help distinguish it from similar sources. This field allows a maximum of 2,000 characters.
3. In the **Source Owner** field, begin typing the name of an owner. Matches appear after you type two or more letters. For more information, refer to [Assigning a Source Owner](<https://documentation.sailpoint.com/saas/help/sources/index.html#assigning-a-source-owner>).
4. Under **Connection Type**, select **Direct Connection** or **Flat File**.

   - **Direct Connection** - A direct connection fetches data from the **Virtual Appliance Cluster** you choose as the application connector for the source. A direct connection configuration allows for real-time updates. For more information about configuring and deploying virtual appliances, refer to the [Virtual Appliance Reference Guide](<https://documentation.sailpoint.com/saas/help/va/index.html>).
   - **Flat File** - Select the flat file if no connector is available, or if another system restricts the connection. This option allows only reading and aggregating data as a generic/delimited application. Provisioning activity is unsupported, and additional configuration pages like connection settings and aggregation settings are unavailable.
5. If you selected **Direct Connection**, in **Virtual Appliance Cluster**, select the virtual appliance cluster that will be used as the application connector for the source.
6. (Optional) Select a governance group to grant its members [source](<https://documentation.sailpoint.com/saas/help/common/users/user_levels.html#source-sub-admin-user-level>) or [role](<https://documentation.sailpoint.com/saas/help/common/users/user_levels.html#role-sub-admin-user-level>) sub-admin level oversight of the source and its access. For more information, refer to [Creating and Managing Governance Groups](<https://documentation.sailpoint.com/saas/help/common/users/governance_groups.html>).
7. If this source represents a primary system containing your organization's personnel records, select the **Authoritative Source** checkbox. For more information, refer to [Creating Identity Profiles](<https://documentation.sailpoint.com/saas/help/setup/identity_profiles.html>).
8. Select **Continue**. The source is created, and you are navigated to the **Source Setup \> Base Configuration** page. Continue to configure your connected source there.

## Base Configuration

Provide the base configuration parameters. Information you entered in the Create New Source dialog is automatically entered into the fields in the Base Configuration page. You can edit this information if necessary.

1. Enter a unique name and description for the source.
2. In the **Source Owner** dropdown list, select the identity that owns this source.

   - To find a source owner, begin entering their name.
3. In the **Virtual Appliance Cluster** dropdown list, select the virtual appliance to use when communicating with your organization's systems. For more information, refer to [SailPoint Virtual Appliances](<https://documentation.sailpoint.com/saas/help/va/index.html>).
4. (Optional) If enabled for your organization, select the **Use a Credential Provider** checkbox to manage the source's authentication using a credential provider.

   > **Note**
   >
   > To add a credential provider, go to **Admin \> Connections \> Credential Providers**. For more information about credential providers, refer to [Credential Providers](<https://documentation.sailpoint.com/connectors/help/credential_providers.html>).
5. Configure the authentication to allow SailPoint to connect to the source. Refer to [Connection Settings](<#connection-settings>) for more information.
6. (Optional) In the **Governance Group for Source Management** dropdown list, select a governance group to associate with this source. For more information about governance groups, refer to [Associating Governance Groups with a Source](<https://documentation.sailpoint.com/saas/help/common/users/governance_groups.html#associating-a-governance-group-with-a-source>).
7. (Optional) Select **Create Manual Work Items** to allow the connector to create manual work items for certain operations. You can also enable this option so the source supports additional source management features such as creating accounts and access profile management.

   > **Important**
   >
   > Once you enable this feature, you cannot disable it.

   For more information on manual work items in SailPoint, refer to [Work Items](<https://developer.sailpoint.com/docs/api/work-items>). For more information on SailPoint features, refer to [SailPoint Identity Services](<https://documentation.sailpoint.com/saas/help/index.html>).
8. Select **Save**.

## Connection Settings

The following information is required for SailPoint to connect and interact with GitLab.

> [!NOTE]
>
> **Screenshot**
>
> [![Connection Settings](<https://documentation.sailpoint.com/connectors/gitlab/va/help/img/personal_access_token.png>)](<https://documentation.sailpoint.com/connectors/gitlab/va/help/img/personal_access_token.png>) [![Group Access Token](<https://documentation.sailpoint.com/connectors/gitlab/va/help/img/group_access_token_1.png>)](<https://documentation.sailpoint.com/connectors/gitlab/va/help/img/group_access_token_1.png>) [![Personal Access Token](<https://documentation.sailpoint.com/connectors/gitlab/va/help/img/personal_access_token_1.png>)](<https://documentation.sailpoint.com/connectors/gitlab/va/help/img/personal_access_token_1.png>)

1. Enter the **Base URL** of your GitLab instance. For example `https://gitlab.example.com`, or `https://gitlab.com` for GitLab SaaS.
2. Select **Self Managed** when the source points at a customer-run instance rather than gitlab.com. This setting allows **Target Groups** to be left empty, so set it correctly for a self-managed instance. The source cannot detect it automatically, because Dedicated and FedRAMP instances run on customer domains.
3. Select an **Authentication Type: Personal Access Token** or **Group Access Token**.
4. Enter the **Access Token**. It must match the type selected above and carry the `read_api` scope. The source refuses the other type when you save it.
5. Enter the **Target Groups**, as group full paths or numeric group IDs. For example `platform` or `platform/tooling`. Subgroups and their projects are included automatically, so name only the top of each tree you want.

   - Required with a personal access token on gitlab.com.
   - Optional with a personal access token on a self-managed instance.
   - Must be left empty with a group access token, which is already confined to one group.
6. Select **Save**.

## Aggregation Settings

> [!NOTE]
>
> **Screenshot**
>
> [![Aggregation Settings](<https://documentation.sailpoint.com/connectors/gitlab/va/help/img/aggregation_setting.png>)](<https://documentation.sailpoint.com/connectors/gitlab/va/help/img/aggregation_setting.png>)

1. Select **Aggregation Settings** from the menu.
2. Enter the **Page Size**. The Page size is the number of account and group records to aggregate in a single page when iterating over large datasets. The default page size is 100.
3. Select **Save**.

## Review and Test

Perform a test to confirm the connection to SailPoint.

1. Go to **Review and Test**.
2. Confirm that the entries in each field are correct.

   If you note any mistakes, return to the section and make corrections.
3. Select **Test Connection**.

## SailPoint Application Onboarding

SailPoint application onboarding enables you to easily onboard new applications and create sources following the successful onboarding of a discovery source. To use this feature, continue to **Discovered Applications** in the SailPoint user interface.

For more information, refer to [Application Onboarding](<https://documentation.sailpoint.com/saas/help/ai/app_onboarding/index.html>) in the SailPoint SaaS documentation.

# Integrating SailPoint with GitLab

Use the GitLab source to manage identity and access in the GitLab application. The GitLab source connects to the GitLab application securely to load data from and provision changes.

This document is designed to give specific information about the requirements and fields needed to successfully configure an instance of the GitLab source.

The connector supports both [GitLab.com](<https://about.gitlab.com/>) and self-managed GitLab instances, including Dedicated deployments on customer domains.

> [!NOTE]
>
> The GitLab connector is read-only. It aggregates and reports. It does not create, update, disable or delete anything in GitLab, and it does not manage entitlement assignments. Provisioning is not supported.

> [!NOTE]
>
> To view the latest features, enhancements, and fixes for all SaaS connectors, refer to the [SaaS Release Notes](<https://community.sailpoint.com/release-notes/saas>) page.

## Supported Features

The GitLab connector supports the following features:

### Account Management

- Account aggregation of GitLab users
- Membership of groups and projects, with the role held on each, reported as account attributes

### Entitlement Management

- Aggregation of GitLab groups as entitlements
- Aggregation of GitLab projects as entitlements

### Non-Human Identity Discovery

- Aggregation of non-human identities: project, group and personal access tokens, group and project service accounts, and security policy bots
- Derived risk indicators on every token, covering expiry, idleness, rotation age and excessive scope or role

For more information, refer to [Machine Identity Security](<https://documentation.sailpoint.com/saas/help/machine/index.html>).

Refer to [Discovering Potential Non-Human Accounts](<https://documentation.sailpoint.com/saas/help/agentic_fabric/nhi/non_human_accounts.html#discovering-potential-non-human-accounts>) for more information.

## Prerequisites

- Configure at least one virtual appliance cluster and successfully test the connection. For more information, refer to the [Virtual Appliance Reference Guide](<https://documentation.sailpoint.com/saas/help/va/index.html>).

The GitLab source authenticates with either a personal access token or a group access token. Both tokens are sent in the same request header, so one field holds the type you declare is verified against the token before every operation, and a mismatch is refused.

### Token Scope

The token requires the `read_api` scope. The connector never writes, so no write scope is needed.

### Choosing a Token Type

|  | Personal access token | Group access token |
| --- | --- | --- |
| Reach | Every group and project its owner belongs to | The single group it was issued on, and everything beneath it |
| Target groups | Required on [GitLab.com](<https://about.gitlab.com/>), optional on self-managed | Not used, and rejected if configured |
| Best for | Governing several unrelated groups with one source | Confining a source to one group tree |

On [GitLab.com](<https://about.gitlab.com/>) a personal access token reaches every group its owner belongs to, and those groups may belong to different organizations. Target groups are therefore mandatory for that combination, so that aggregation cannot pull another organization's users into your tenant. A self-managed instance holds one organization, so the list is optional there.

> [!NOTE]
>
> A project access token is not supported as a source credential and is refused.

### Roles the Token Needs

What the token can see determines what the source reports. A missing role does not fail the aggregation. GitLab refuses that one listing, and the source skips it. An under-privileged token yields a partial result rather than an error.

| To aggregate | The token needs |
| --- | --- |
| Users, groups and projects in a group tree | At least Reporter on the groups concerned |
| A group's access tokens and its service accounts | Owner on that group |
| A project's access tokens | Maintainer or Owner on that project |
| Instance administrator, self-managed only | Instance administrator, self-managed only |
| Every personal access token on the instance | Instance administrator, self-managed only |

### GitLab Tier

Service accounts and the group credentials inventory are GitLab Premium and Ultimate features. On Free, those datasets return no rows. Accounts, entitlements and access tokens are unaffected.

# Schema Reference

The application schema is used to configure the objects returned from a connector.

> [!NOTE]
>
> - The **Account Schema** tab is used to define the attributes for each object type in the application being configured. The schema attributes can be defined as **Entitlement** or **Multi-Valued**. Refer to [Managing Source Account Schemas](<https://documentation.sailpoint.com/saas/help/accounts/schema.html>) for more information.
> - The schema attributes that are not present by [default](<#default-account-schema>) must be defined as strings if not specified.

The GitLab connector uses the following default correlation and object configurations.

## Default Account Schema

Each source supports a variety of details, or attributes, about each user who has an account, such as their name, email address, manager name, and location.

The set of account attributes each source stores and how they're organized is known as the account's *schema*. To best represent your data, you can configure sources to use an account schema matching the one you use in the external connector. Refer to [Managing Source Account Schemas](<https://documentation.sailpoint.com/saas/help/accounts/schema.html>) for more information.

### Default Account Attributes

The GitLab connector supports the following default account schema attributes and customer configurable attributes. The attributes must be defined as strings if not specified.

| Attribute Name | Description |
| --- | --- |
| id | Numeric GitLab user ID. Account identity |
| username | GitLab username. Display attribute |
| name | Display name |
| public\_email | Public email address, used for correlation. Empty unless the user has published one |
| state | GitLab account state, for example active or blocked |
| locked | Whether the account is locked. |
| groups | Multi-valued. The groups the user belongs to |
| projects | The Multi-valued. The projects the user belongs to |
| groupPermissions | The Multi-valued. Role held on each group, as `Role@full/path` |
| projectPermissions | The Multi-valued. Role held on each project, as `Role@full/path` |

## Default Entitlement Attributes

Entitlement attributes define the entitlements, such as groups or roles, that can be assigned to the managed system's user accounts. Refer to [Managing Entitlements](<https://documentation.sailpoint.com/saas/help/access/entitlements.html>) for more information.

> [!CAUTION]
>
> Changing the attribute marked as the Entitlement ID after aggregating accounts or entitlements can result in duplicate entitlements being created, or access profiles and roles breaking. To avoid this, edit the entitlement schema before performing any aggregations.

Two entitlement types. Both key on the numeric `id` and display the full path, because groups of the same name in different trees are otherwise indistinguishable.

This section describes the entitlement attributes for group.

| Attribute Name | Description |
| --- | --- |
| id | GitLab numeric group ID |
| full\_path | Unique path of the GitLab group |
| name | Display name of the GitLab group |
| description | Description recorded on the GitLab group |
| visibility | Visibility of the GitLab group |
| parent\_id | ID of the parent GitLab group |
| web\_url | URL of the GitLab group |

This section describes the entitlement attributes for project.

| Attribute Name | Description |
| --- | --- |
| id | GitLab numeric group ID |
| path\_with\_namespace | Unique path of the GitLab project |
| name | Display name of the GitLab project |
| description | Description recorded on the GitLab project |
| visibility | Visibility of the GitLab project |
| archived | True when the GitLab project is archived and read-only |
| web\_url | URL of the GitLab project |

## Machine Identities

The source reports six datasets. Each dataset reports one kind of holder. Tokens are reported as credentials. Bots and service accounts are reported as machine accounts.

| Dataset | Reports | Requires |
| --- | --- | --- |
| Project access tokens | The token and the bot user it runs as | Maintainer or Owner on the project |
| Group access tokens | The token and its bot user | Owner on the group |
| Personal access tokens | The token only. Its holder already aggregates as an account | Instance administrator on self-managed. Otherwise a top-level group's credentials inventory, which is a Premium and Ultimate feature |
| Group service accounts | The service account and its tokens | Owner on a top-level group. Premium or Ultimate |
| Project service accounts | The service account and its tokens | Premium or Ultimate |
| Security policy bots | The bots only. They hold no credentials | Visibility of project members |

Every token row carries `tokenType` as `personal`, `group`, or `project`. A credential is identifiable without referring to the dataset it arrived in. A token row names its bot through `user_id`. A bot row names its token through `tokenId`. This links a credential and the identity that uses it. A bot that holds several tokens is reported once.

### Risk Indicators

Every token carries a multi-valued `riskFlags` attribute. It also carries the measure behind each flag, so a reviewer can see how far past a threshold a token is: `daysUntilExpiry`, `daysSinceLastUse`, `tokenAgeDays`, and `lifetimeDays`.

A token with nothing wrong carries an empty array. If GitLab does not report a date, the source omits the measures that need it. The run does not fail.

| Flag | Meaning |
| --- | --- |
| `ABOUT_TO_EXPIRE` | Expires within the warning window, 30 days by default |
| `EXPIRED_NOT_REVOKED` | Past expiry but never revoked. GitLab no longer honours it, yet it remains on the books. |
| `IDLE` | Unused for the idle threshold, 90 days by default |
| `NEVER_USED` | Never used at all, and old enough that it would have been by now, 14 days by default |
| `LONG_EXPIRATION` | Issued with a lifetime longer than a year by default |
| `NOT_ROTATED` | Older than the rotation threshold, 90 days by default |
| `OVER_SCOPED` | Holds `api` or `write_repository`, granting write access across everything the holder reaches |
| `OVER_PRIVILEGED` | Holds Maintainer or above. A personal access token carries no role, so it is never flagged. |

# Troubleshooting

If you encounter any of the following issues or errors, SailPoint recommends that you follow the guidance provided below to resolve the error before contacting SailPoint Support.

For issues or errors that are not addressed in this connector guide, refer to the following resources for troubleshooting information:

- [SailPoint Identity Services Documentation](<https://documentation.sailpoint.com/saas/help/index.html>)
- [SailPoint Support Knowledge Base](<https://support.sailpoint.com/csm?id=kb_view2&amp;kb_id=05ff44289f011200550bf7b6077fcfa3>)
- [SailPoint Developer Community](<https://developer.sailpoint.com/>)

## The configured token is not a GitLab group access token

**Issue:** Authentication Type is set to Group Access Token, but the token supplied is a personal access token.

**Resolution:** Supply a group access token. Or change Authentication Type to Personal Access Token and configure target groups.

## The configured token is a group or project access token, not a personal access token

**Issue:** Authentication Type is set to Personal Access Token, but the token supplied is a group or project access token.

**Resolution:** Supply a personal access token. Project access tokens are not supported as a source credential.

## Target groups are required

**Issue:** The source uses a personal access token on gitlab.com, and Target Groups is empty.

**Resolution:** Enter the groups you want to aggregate. Refer to [Connection Settings](<https://documentation.sailpoint.com/connectors/gitlab/va/help/connecting.html#connection-settings>).

## Target groups are not allowed with a group access token

**Issue:** Target Groups is set, but the source uses a group access token.

**Resolution:** Clear Target Groups. A group access token is confined to one group, which the source discovers.

## The token belongs to no group

**Issue:** A group access token, or a non-administrator personal token, belongs to no group. Nothing is in scope to aggregate.

**Resolution:** Grant the token membership of the groups you want to govern.

## Accounts appear as deleted after a previously successful run

**Issue:** Accounts that aggregated successfully now appear as deleted.

**Resolution:** The token might have lost instance administrator rights. This narrows the scope from the whole instance to the groups it belongs to. Check the connector log. It records the resolved scope at the start of every run. Restore the rights, or set target groups explicitly.

## Groups or projects are missing from a run

**Issue:** Some groups or projects do not appear in the aggregation results.

**Resolution:** The token most likely lacks the role that listing requires. GitLab refuses the listing. The source skips that node and logs it rather than failing the run. Check the log for skipped nodes. Compare them against the role table in [Prerequisites](<https://documentation.sailpoint.com/connectors/gitlab/va/help/index.html#prerequisites>).

## Fewer machine identities than expected

**Issue:** The source returns fewer machine identities than expected.

**Resolution:** Service accounts and the credentials inventory need Premium or Ultimate. Group and project token listings need Owner or Maintainer. The source logs the resolved scope at the start of each aggregation. It logs the row and skip counts at the end. Check those two lines first.