> ## 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 Token

*Lumos offers three GitLab connectors for GitLab.com / cloud-hosted groups and self-managed instances, each its own integration card. This article covers **GitLab (Token)**, where you authenticate with a personal or group access token. To authorize Lumos in the browser instead, use GitLab (OAuth). For a self-managed instance (cloud or on-prem), use GitLab Self-Hosted, which works at the instance level and uses an Account Base URL plus a personal access token.*

## After this article

You'll be able to connect a GitLab.com group to Lumos with an access token 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 | Yes | Groups in GitLab. Lumos adds and removes group members |
| Group Role | Permission | Yes | Yes | Group roles, including Ultimate custom member roles |
| Projects | Permission | Yes | Yes | Projects in GitLab. Lumos adds and removes project members |
| Project Role | Permission | Yes | Yes | Project roles, including Ultimate custom member 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 | Deactivates the user by setting the membership to `awaiting` |

**Provisioning behavior:**

* **Create:** Lumos invites the user to the parent group by email with exactly one Role entitlement, either a default access level (Guest through Owner) or an Ultimate custom member role. The account shows **Pending** until the invitation is accepted.
* **Assign a Group or Project:** Lumos adds the user as a member with the default **Developer** role.
* **Assign a Role:** Lumos first adds the user to the group or project if they aren't a member yet (existing membership is fine), then sets the access level for a default role or the member role ID for a custom role.
* **Unassign a Role:** for a custom role, Lumos clears the member role and sets the access level to **Guest**. For default roles, unassigning **Guest** or **No Access** removes the membership entirely, and unassigning any higher role drops the user to **Guest**.
* **Reactivate:** Lumos sets the group membership state back to `active`. Reactivating an already-active user fails with "User is already active".
* **Deactivate:** sets the membership state to `awaiting`. Deactivating an already-suspended user fails with "User is already suspended".
* **Delete:** removes the user from the parent group. If they aren't a direct member there, Lumos removes them as a billable member instead, which also clears direct memberships in subgroups and projects.

Activity tracking is 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 available through this integration.

## Required plan and roles

* **GitLab role:** ensure you're an **admin and owner** in GitLab before you start. You must be an administrator to create a token that Lumos can use.
* **Token type:** a **personal access token** or a **group access token**. In both cases the **api** scope is required for full functionality. When you use a group access token, make sure the token has access to the parent group you supply in the connection fields.
* **GitLab tier notes:** custom member roles sync requires GitLab **Ultimate**. Activity tracking covers **billable members** only.
* **Lumos plan:** no minimum plan requirement is documented for this integration.

## Read-only access vs provisioning

**Is read-only possible?** No. GitLab (Token) requires the `api` scope for full functionality, with no narrower read-only scope documented here. 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.** A personal or group access token with the `api` scope, created by a GitLab admin and owner, entered on this card along with the Parent Group slug. Follow the steps below.

**Watch out for.** A group access token must have access to the Parent Group you enter, or syncs return nothing. Custom member role sync requires GitLab Ultimate, and activity tracking only covers billable members. If you need read-only access to the same group, connect through GitLab (Multi-auth) rather than narrowing this card's token, since no read-only scope is documented for GitLab (Token) itself.

## Instructions

**Phase 1: Create an access token in GitLab**

1. Log into your GitLab instance as an administrator.
2. Go to **User Settings > Access Tokens**.
3. Click **Add new token**.
4. Give the token a name and select the **api** scope.
5. Click **Create token**.
6. Copy the token so you can paste it into Lumos.

**Phase 2: Connect in Lumos**

1. Find the **GitLab (Token)** card in your Lumos integrations (reconnect an existing card or add a new one).
2. Paste your token into the **GitLab Token** field.
3. Fill in the remaining 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

**The token can't create or read what Lumos needs.** Confirm the token carries the **api** scope. Read-only scopes won't support provisioning (adding or removing members, changing roles, invitations).

**Group access token can't see the parent group.** When you use a group access token, the token must have access to the parent group you enter in the **Parent Group** field. Recreate the token against the correct parent group if syncs return nothing.

**Custom member roles aren't syncing.** Custom member roles are available on GitLab **Ultimate** only. On lower tiers the `/groups/{id}/member_roles` endpoint returns no custom roles.

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