> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gitlab OAuth

*Lumos offers three GitLab connectors for GitLab.com / cloud-hosted groups and self-managed instances, each its own integration card. This article covers **GitLab (OAuth)**, where you authorize Lumos in the browser during connection. To connect with a personal/group access token instead, use GitLab (Token). For a self-managed instance (cloud or on-prem), use GitLab Self-Hosted, which works at the instance level and can additionally create, block, and delete users.*

## After this article

You will be able to connect a GitLab.com group to Lumos via OAuth to sync users, groups, group roles, projects, and project roles, then provision, deprovision, and review that access from Lumos.

## Capabilities

| Functionality | Type | Sync | Provision | Description |
| :- | :- | :- | :- | :- |
| Users | Account | Yes | Yes | User account records |
| Groups | Permission | Yes | No | Groups in GitLab |
| Group Role | Permission | Yes | Yes | Group roles |
| Projects | Permission | Yes | No | Projects in GitLab |
| Project Role | Permission | Yes | Yes | Project roles |

| Deprovisioning Action | Type | Description |
| :- | :- | :- |
| Delete | User | Removes the user from the parent group, then removes any inherited memberships from subgroups and projects |
| Deactivate | User | Sets the user's parent-group membership to `awaiting` (the user is not removed) |

**Account lifecycle details:**

* **Create Account**: invites a user (by email, with an optional default role) to the parent group of the connected organization.
* **Activate Account**: sets the user's parent-group membership back to an active state.
* **Assign / Unassign Entitlement**: adds or removes the user as a member of a group or project, depending on the selected entitlement.
* **Activity tracking**: supported for billable members only (members counted in your GitLab subscription), covering last activity date (`last_activity_on`) and last login date (`last_login_at`). Non-billable members (free-tier, guest users) have no activity data.

## Required plan and roles

* **Lumos plan:** No minimum plan requirement is documented for this integration.
* **GitLab role:** ensure you are an **admin and owner** of the GitLab group you want to connect before authorizing.
* **OAuth scopes:** Lumos requests scopes during the authorization flow, and GitLab validates that the requested scopes match the scopes configured on the OAuth application. This card authorizes a single credential that carries the connector's full read and write capability set, covering sync as well as provisioning (adding or removing members, changing roles, invitations). No read-only configuration is documented for this card. For a read-only connection to a GitLab.com group, use GitLab (Multi-auth).
* **GitLab tier notes:** custom member roles sync requires GitLab **Ultimate**. Activity tracking covers **billable members** only.

## Read-only access vs provisioning

**Is read-only possible?** No. GitLab (OAuth) authorizes a single credential that carries the connector's full read and write capability set, and no read-only configuration is documented for it. For a read-only connection to a GitLab.com group, use the GitLab (Multi-auth) connector instead and choose its Read-only OAuth path or a `read_api`-scoped access token.

**What full provisioning requires.** The OAuth authorization completed in the steps below, which enables adding or removing members, changing roles, and sending invitations alongside the sync. Make sure the OAuth application is configured with the scopes Lumos requests before you authorize.

**Watch out for.** GitLab rejects the OAuth connection outright if the scopes Lumos requests don't match what's configured on the OAuth application, so confirm the application's configured scopes before connecting. Custom member role sync requires GitLab Ultimate, and activity tracking only covers billable members.

## Instructions

**Phase 1: Prepare GitLab**

1. Log in to GitLab as an admin/owner of the group you want to connect. No credential needs to be created ahead of time, since you will authorize Lumos in the browser during connection.

**Phase 2: Connect in Lumos**

1. Find the **GitLab (OAuth)** card in your Lumos integrations.
2. Click **Connect** and complete the GitLab authorization flow. The OAuth application's configured scopes must match what Lumos requests, or GitLab rejects the connection.
3. Fill in the connection fields:
   * **Parent Group**: the parent group slug to scope this connector instance to. This is the group slug that appears in GitLab URLs after `https://gitlab.com/`. To find it, log in to GitLab at `https://gitlab.com`, go to **Groups → Your Groups** at `https://gitlab.com/dashboard/groups`, click the group you want, and read the slug from the address bar. Examples: if your group URL is `https://gitlab.com/my-org`, use `my-org`. For a subgroup at `https://gitlab.com/my-org/team-a`, the parent group is `my-org`. For a project at `https://gitlab.com/my-org/team-a/project-1`, the parent group is `my-org`. This connector instance will only have access to subgroups and projects nested under this parent group.
   * **Sync only billable users**: by default Lumos fetches all users from GitLab. Check this option to sync only billable users.

## API Endpoints Used

<Note>
  The API endpoints this integration uses are available to logged-in Lumos customers. [Log in](/login) to view them.
</Note>

## Troubleshooting

**Syncs fail or the connector drops to a Failed state periodically.** GitLab enforces low API rate limits (on the order of \~10 requests/minute on some endpoints), which can fail syncs and account-finder runs. The connector paces itself against the limit, but heavy activity syncs can still hit downstream rate limits even while the main sync stays healthy. The connector may not always auto-reconnect after a rate-limit failure, so reconnect manually if it stays Failed.

**Reconnecting via the connection drawer fails with "Failed to forward OAuth callback to ICS".** This was a Lumos-side reconnect bug (the flow tried to create a duplicate connection). It has been fixed. If the integration shows connected and the main sync succeeds, no re-auth is required. An expired OAuth token that can no longer be refreshed does require a successful reconnect to resume syncs.

**Sync fails with 404 "Group Not Found".** This indicates a referenced group was removed or is inaccessible. Current connector versions skip such groups instead of failing the sync. If you still see this, reconnect with a credential that can access the group or update the connection.

**OAuth connection rejected over scopes.** GitLab validates that the scopes Lumos requests match the scopes configured on the OAuth application. Update the OAuth application so its configured scopes match, then authorize again. If you need a read-only connection, connect through GitLab (Multi-auth) instead.

**Users missing from Lumos.** On connector versions that read users via GitLab's SCIM API, only SCIM-provisioned users in the connected group are returned. Users not managed via SCIM will not appear in Lumos. Status mapping on those versions: active → Active, deactivated → Suspended, deleted → Deprovisioned.

**No activity data for some users.** Activity tracking only covers billable members under your GitLab subscription. Free-tier and guest users have no activity data.