GitLab

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 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.
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.

Option A: Group access token (Recommended)
Option B: Personal access token (Free plan)
Option C: Service account token (Ultimate)

A group access token is attached to the group rather than a person - GitLab creates a bot user (group_<id>_bot_...) for it, and it keeps working regardless of who created it.

Open the group

In the top bar, select Search or go to and find the group you want to connect.

Open access tokens

In the left sidebar, select Settings -> Access tokens.

Create the token

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. 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

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.

Open personal access tokens

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.

Generate a legacy token

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:

From the Generate token dropdown, select Legacy token.
Set Token name, for example Oleria.
Set Expiration date (required, defaults to 365 days).
Set Scopes to api.
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 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.

Create the service account

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_<id>_<hash>. Select Create service account.

Add it to the group as Maintainer or Owner

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.

Create the API token on that account

Service accounts have no password and cannot open Edit profile, so create the token from the group’s Service accounts page:

Select Settings -> Service accounts.
On the account you just created, select the vertical ellipsis (…) -> Manage access tokens.
Select Add new token.
Set Token name, for example Oleria.
Set Expiration date (required, unless your group turned off required expiration for service-account tokens under Settings -> General -> Permissions and group features).
Set Scopes to api.
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/<path>`)

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

Open the integration

Go to your Oleria workspace, select Integrations -> select GitLab.

Complete the connection form

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).

Oleria connect with GitLab panel showing the Group ID, Access Token, and GitLab Base URL fields alongside the GitLab features, setup instructions, and supported data objects

Save the integration

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.

Overview

Integration Studio

Applications

Ticketing

Messaging

What Oleria discovers

Plan coverage

Prerequisites

Token role: Maintainer vs Owner

Create an access token in GitLab

Find the Group ID

Connect GitLab to Oleria

Verify the integration

Remediation actions

What this integration does not cover

Contact us

​What Oleria discovers

​Plan coverage

​Prerequisites

​Token role: Maintainer vs Owner

​Create an access token in GitLab

​Find the Group ID

​Connect GitLab to Oleria

​Verify the integration

​Remediation actions

​What this integration does not cover

​Contact us

What Oleria discovers

Plan coverage

Prerequisites

Token role: Maintainer vs Owner

Create an access token in GitLab

Find the Group ID

Connect GitLab to Oleria

Verify the integration

Remediation actions

What this integration does not cover

Contact us