> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oleria.com/llms.txt
> Use this file to discover all available pages before exploring further.
# GitLab
> Connect your GitLab group to Oleria to continuously discover members, projects, roles, non-human identities, and activity across your DevSecOps platform.
Connect GitLab to Oleria to see who has access to a GitLab group and everything under it: human members, subgroups, projects, protected branches, standing access grants, and the tokens, keys, and bots that act as non-human identities (NHIs). Oleria reads this data from the GitLab REST API, and GraphQL where available for Duo Agent Platform catalog agents. This page walks through creating an access token in GitLab and connecting it to your Oleria workspace.
GitLab.com and self-hosted GitLab are both supported. One Oleria connection maps one root group and every subgroup and project beneath it. Connect additional groups as separate instances if you operate more than one top-level group.
The Oleria connection form's **Access Token** field accepts any of three credentials: a group access token, a personal access token, or a GitLab service account's personal access token. All three authenticate the same way against the GitLab API. Use a dedicated group access token or service account, not an employee's personal access token - if that employee leaves and their account is disabled, the integration breaks.
## What Oleria discovers
Once connected, Oleria continuously discovers and maps the following from the configured GitLab group:
* **Accounts** - group members (seat-consuming users on Premium and above; all members on Free), including username, name, state, and multi-factor authentication (MFA) status when GitLab exposes it. Service accounts are detected on Ultimate.
* **Roles** - GitLab's built-in access levels (Guest, Planner, Reporter, Developer, Maintainer, Owner, and related levels) and Ultimate custom member roles with their granular permissions.
* **User groups** - the root group and every descendant subgroup, including nested group membership.
* **Resources** - projects in the group tree, plus protected branches as their own resources (push and merge access).
* **Access** - who can reach which project, including:
* direct group membership
* inherited membership from ancestor groups
* group and project shares (the lower of the member's role in the source group and the share level)
* direct project membership (outside collaborators)
* named protected-branch access control lists (user, group, or deploy key)
* **Non-human identities (NHIs)** - personal, group, and project access tokens; deploy tokens and deploy keys; cluster agent tokens; group and project CI/CD runners; pipeline trigger tokens; CI/CD job-token inbound allowlists; OAuth applications when the token can list them; Duo Agent Platform catalog agents when the API allows.
* **Activity** - group and project audit events (Premium and above), including membership changes, token and deploy-key events, protected-branch changes, and authentication events.
Standard integrations are configured read-only. Remediation uses the same credential with write access, and is opt-in, see [Remediation actions](#remediation-actions) below.
### Plan coverage
What GitLab returns depends on the group's plan. If a feature isn't available on your plan, Oleria simply skips it and continues syncing everything else, rather than failing the connection:
| GitLab plan | What Oleria gets |
| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Free | Members, groups, projects, protected branches, and access. No billable-member seat list, no audit events, and no group or project access tokens on GitLab.com. |
| Premium and above | Everything on Free, plus billable members, audit events, and group and project access tokens. |
| Ultimate | Everything on Premium, plus service account detection and custom member roles. |
Group access tokens require Premium or Ultimate on GitLab.com, and are not available on a GitLab.com trial. Self-managed GitLab supports group access tokens on any license. On Free, use a personal access token instead.
## Prerequisites
* A GitLab group you want Oleria to inventory (GitLab.com or self-hosted).
* A credential that is **Maintainer** or **Owner** on that group. Maintainer is enough to connect and inventory members, projects, and most access; **Owner is recommended** for full coverage, see [Token role: Maintainer vs Owner](#token-role-maintainer-vs-owner).
* Creating a group access token still requires **you** to be Owner of the group in GitLab, even though the token itself can be scoped to Maintainer. That is a GitLab UI gate, not an Oleria requirement.
* For self-hosted GitLab, the instance URL (for example, `https://gitlab.example.com`).
## Token role: Maintainer vs Owner
Oleria does not reject a Maintainer-level credential at connect time. **Authenticate** only checks that the credential can see the configured group.
| Credential's role on the group | What Oleria gets |
| :------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Maintainer (minimum useful role) | Members, subgroups, projects, the access graph, protected branches, project access tokens (Premium and above), deploy keys, and audit events (Premium and above). The Premium seat list (billable members) is Owner-only in GitLab, so Oleria falls back to the full members list. Group access tokens, group deploy tokens, and GitLab's service accounts API are skipped. |
| Owner (recommended) | Everything Maintainer sees, plus billable members (who consumes a seat) (Premium and above), group access tokens (Premium and above), group deploy tokens, service account detection (Ultimate only), member two-factor authentication (2FA) status when GitLab exposes it, and group membership and project visibility remediation. |
Developer and below can sometimes see the group, but miss project-token and deploy-key inventory. Do not use those roles for this integration.
## Create an access token in GitLab
A group access token is the preferred credential because it is tied to the group, not to a person. Use a personal access token on Free plans, or a service account token if your group is on Ultimate and you want a dedicated bot identity for the connection.
A [group access token](https://docs.gitlab.com/user/group/settings/group_access_tokens/) is attached to the group rather than a person - GitLab creates a bot user (`group__bot_...`) for it, and it keeps working regardless of who created it.
In the top bar, select **Search or go to** and find the group you want to connect.
In the left sidebar, select **Settings** -> **Access tokens**.
Select **Add new token** and set:
| Field | Value |
| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Token name | A dedicated name, for example `Oleria`. Visible to anyone who can view the group. |
| Token description | Optional. |
| Expiration date | Required. Defaults to 365 days if left blank. The token expires at midnight UTC on that date. |
| Role | **Owner** recommended for full coverage. **Maintainer** works with reduced coverage, see [Token role: Maintainer vs Owner](#token-role-maintainer-vs-owner). GitLab defaults this field to Maintainer, and creating the token still requires you to be Owner of the group. |
| Scopes | **`api`** - the only scope this integration needs. |
Select **Create group access token**.
Copy the token immediately (the prefix is usually `glpat-`). GitLab does not show it again after you leave the page.
Treat this token like a password. Anyone with it can read what its role is allowed to see; at Owner, it can also change group membership and project visibility.
Use this when group access tokens are unavailable, for example on GitLab.com Free or trial. The user who owns the token must be at least **Maintainer** of the group; **Owner** is recommended for full coverage.
Select your avatar in the upper-right corner, select **Edit profile**, then in the left sidebar select **Access** -> **Personal access tokens**. On GitLab.com, you can also go directly to `https://gitlab.com/-/user_settings/personal_access_tokens`.
Prefer a dedicated bot or service account user over an individual employee's account. If that account is blocked or the employee leaves, the token dies with it.
GitLab.com now defaults to **granular** personal access tokens, which work only if every REST resource Oleria reads is allowed on the token. A missing granular permission fails the sync (`insufficient_granular_scope`) instead of looking like an empty group. To avoid that:
1. From the **Generate token** dropdown, select **Legacy token**.
2. Set **Token name**, for example `Oleria`.
3. Set **Expiration date** (required, defaults to 365 days).
4. Set **Scopes** to **`api`**.
5. Select **Generate token** and copy it immediately.
If you already have a granular personal access token and want to keep it, confirm it can call the group, members, projects, tokens, and, on Premium and above, audit-event APIs before pasting it into Oleria.
GitLab [service accounts](https://docs.gitlab.com/user/profile/service_accounts/) are non-human users that cannot sign in to the GitLab UI and authenticate with their own personal access token. This is optional - create one only if you want a dedicated bot identity instead of a group access token. On GitLab.com, only a top-level group Owner can create one.
In the top bar, select **Search or go to** the top-level group. In the left sidebar, select **Settings** -> **Service accounts**, then select **Add service account**. Enter a name, for example `Oleria` - GitLab generates a username such as `service_account_group__`. Select **Create service account**.
Service accounts have no access until you invite them. Add the new account to the group from **Manage** -> **Members** -> **Invite members** (or the group members API):
* **Maintainer** - enough to connect and inventory members, projects, and most access.
* **Owner** (recommended) - full coverage, including group tokens, the seat list, and remediation.
If you assign Owner, that account's personal access tokens also act as Owner on the group.
Service accounts have no password and cannot open **Edit profile**, so create the token from the group's **Service accounts** page:
1. Select **Settings** -> **Service accounts**.
2. On the account you just created, select the vertical ellipsis (**...**) -> **Manage access tokens**.
3. Select **Add new token**.
4. Set **Token name**, for example `Oleria`.
5. Set **Expiration date** (required, unless your group turned off required expiration for service-account tokens under **Settings** -> **General** -> **Permissions and group features**).
6. Set **Scopes** to **`api`**.
7. Select **Create personal access token** and copy it.
Paste that token into Oleria's **Access Token** field - the same field a group access token or personal access token uses.
## Find the Group ID
Oleria accepts either value:
| What you paste | Example | Where to get it |
| :--------------- | :---------------------------- | :------------------------------------------------------------ |
| Numeric group ID | `12345678` | Group overview -> **Actions** (ellipsis) -> **Copy Group ID** |
| Group path | `my-org` or `my-org/platform` | The path in the group URL (`gitlab.com/groups/`) |
Both resolve to the same group. The numeric ID is stable if you rename the group; the path is easier to read.
## Connect GitLab to Oleria
Go to your Oleria workspace, select **Integrations** -> select **GitLab**.
Fill in the connection form:
| Field | Notes |
| :-------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Group ID | Required. Numeric ID from the group overview page, or the full group path. |
| Access Token | Required. A group access token, personal access token, or GitLab service account personal access token, with the `api` scope. Maintainer can connect; Owner is recommended for full coverage. |
| GitLab Base URL | Optional. Defaults to `https://gitlab.com`. Set this for self-hosted instances (no `/api/v4` suffix). |
Select **Authenticate**. Oleria calls GitLab for the configured group to confirm the credential can see it before saving.
## Verify the integration
Confirm the GitLab instance appears in your Oleria workspace's connected integrations. After the first sync completes, you can review the discovered accounts, groups, projects, NHIs, and access. Audit event activity (Premium and above) syncs on a separate, more frequent cadence.
If you rotate or revoke the credential, edit the integration in Oleria, paste the new value, and select **Update**. The next sync runs with the new credential.
On GitLab.com, Oleria throttles requests to stay within GitLab's authenticated Ultimate caps: 2,000 requests per minute and 25,000 per hour. Self-hosted instances use whatever limits you configured on the GitLab side.
## Remediation actions
Standard integrations are configured read-only. If you enable remediation for GitLab, Oleria uses the same credential. GitLab requires **Owner** to manage group members and to change project visibility; removing a direct project membership only needs Maintainer or above on that project.
| Action | What it does | Revert |
| :------------------------------------- | :------------------------------------------------------------------------ | :---------------------------------------------------------------------- |
| Remove user from group or disable user | Removes the account from the GitLab group. | Supported - re-adds the member at their previous access level. |
| Add user to group or enable user | Adds the account to the GitLab group. | Supported - removes the member from the group. |
| Revoke anonymous access | Sets the project's visibility to private. | Supported - restores the previous visibility. |
| Revoke permission to a project | Removes a direct project membership. Inherited group access is unchanged. | Supported - re-adds the direct membership at the previous access level. |
Revoking anonymous access makes a public or internal project private. Confirm that change with the project owners before running it.
Removing a member only deletes direct membership on that group. If they still inherit access from a parent group or a share link, they will still appear on projects until those other paths are removed.
## What this integration does not cover
* **Instance-wide (shared) runners** - only group- and project-scoped runners are modeled.
* **Snippets** - not treated as access-controlled resources.
* **SAML group links** - GitLab is the service provider; the identity provider remains the authority for those memberships.
* **Group-owned OAuth applications on GitLab.com** - enumerated when GitLab's API allows, and skipped without failing the sync if it does not.
* **Duo Agent Platform** - catalog agents are best-effort; missing API access is skipped unless the token is a fine-grained token missing a required scope.
## Contact us
For questions about this integration, contact us at [support@oleria.com](mailto:support@oleria.com).