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. 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 last activity. With an Owner credential, or a GitLab administrator’s credential on self-managed GitLab, Oleria also reads each member’s email, multi-factor authentication (MFA) status, and whether they sign in through the group’s single sign-on (SSO), when GitLab exposes them. Service accounts are detected with an Owner credential (GitLab 18.10 and later on any plan; Ultimate on earlier versions).
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, including when each token was last used; with an Owner credential, enterprise users’ personal access tokens (GitLab.com, Premium and above, from the top-level group) and service account tokens; with a GitLab administrator’s credential, every personal access token on the instance; deploy tokens and deploy keys; cluster agent tokens; group and project CI/CD runners; pipeline trigger tokens; CI/CD job-token inbound allowlists; instance OAuth applications when the credential belongs to a GitLab administrator; Duo Agent Platform catalog agents, including whether each agent is enabled, 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.

Remediation is opt-in and uses the same credential. 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 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 custom member roles. Before GitLab 18.10, service account detection also needs Ultimate.

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. Owner is recommended. Maintainer connects and inventories members, projects, and most access, but misses group access tokens, group deploy tokens, the billable seat list, service account detection, enterprise users’ personal access tokens, and the Disable NHI and Revoke anonymous access remediation actions.

Compare what Maintainer and Owner can see

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 (GitLab 18.10 and later on any plan; Ultimate on earlier versions), member email, two-factor authentication (2FA) status, and SSO link when GitLab exposes them, enterprise users’ personal access tokens (GitLab.com, Premium and above), and the remediation actions that need Owner: Disable NHI and Revoke anonymous access. Maintainer already covers group membership, role, and project-access 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 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

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 on the Connected tab of your Oleria Integrations page. 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. Adding and removing group members, adding and removing roles, and revoking project access need Maintainer or above on the configured group. Disable NHI and Revoke anonymous access need Owner on the configured group. Disabling and enabling a user needs Owner on the top-level group (Premium and above), or a GitLab administrator’s credential.

Action	What it does	Revert
Add user to group	Adds the account to the selected GitLab group or subgroup as Guest. Use Add user to role to grant a higher role.	Supported - removes the member from the group.
Remove user from group	Removes the account from the selected group, and from every subgroup and project under it where they were a direct member.	Partially supported - re-adds the member to the group with their previous access level, expiration date, and custom role. Memberships removed from subgroups and projects are not restored.
Disable user	With an administrator’s credential, blocks the user on the whole GitLab instance. Otherwise, sets the member to Awaiting on the top-level group, which removes their access to every subgroup and project under it. This only works for members of the top-level group itself; for someone who only has access on a subgroup or project, use Remove user from group on that subgroup or Revoke permission to a project. Only active or blocked users can be changed.	Supported - unblocks the user, or sets the member back to Active.
Enable user	Unblocks the user, or sets an awaiting member back to Active on the top-level group.	Supported - reverses the change.
Add user to role	Grants the member a standard access level or custom member role on the configured group, or adds them to the group with that role. It never lowers access: if the member already has a higher standard role, nothing changes, and a custom role below their current level is refused. To lower a role, use Remove user from role.	Supported - restores the previous role, or removes the account if they were not a member before.
Remove user from role	Demotes the member to Guest on the configured group. Guest and Minimal Access cannot be removed with this action, use Remove user from group instead.	Supported - restores the previous role.
Disable NHI	Revokes the NHI’s credential: a personal, group, or project access token, a deploy token, a pipeline trigger token, or a cluster agent token. A deploy key is removed from every project in the group where it is enabled. Runners, job-token allowlist entries, OAuth applications, and Duo agents cannot be disabled. Oleria refuses to revoke the token this connection uses.	Not supported - GitLab revocation is permanent. Create a new credential if you need it again.
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.

Disable NHI cannot be undone. Anything that uses the revoked token, key, or trigger stops working immediately. Confirm the credential is unused, or plan its replacement, before running it. A deploy key is removed from every project in the group that uses it. If some removals fail, the action reports a partial failure and the key stays on the remaining projects.

Remove user from group also removes the member’s direct memberships on every subgroup and project under that group, and reverting it restores only the group membership. With an administrator’s credential, Disable user blocks the user across the whole GitLab instance, including groups and projects this connection does not govern.

Removing a member deletes their direct memberships on that group and everything under it. 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. To cut off a member of the top-level group everywhere under it at once, use Disable user instead.

Known limitations

Instance-wide (shared) runners aren’t discovered. Only group- and project-scoped runners are.
Snippets aren’t discovered as resources.
SAML group links aren’t used as the source of membership. GitLab is the service provider, so your identity provider remains the authority for those memberships.
Group-owned OAuth applications aren’t discovered. Oleria lists instance OAuth applications only when the credential belongs to a GitLab administrator.
SSH keys and active sessions aren’t discovered. GitLab also has no API to end a member’s sessions.
Duo Agent Platform catalog agents are best effort. Oleria skips them when API access is missing, unless the token is a fine-grained token that lacks a required scope.

Contact us

For questions about this integration, contact us at support@oleria.com.

Overview

Generic connectors

Identity providers

HR systems

Cloud infrastructure

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

Known limitations

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

​Known limitations

​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

Known limitations

Contact us