Skip to main content
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

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

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