Skip to main content
Lumos offers three GitLab connectors, each its own integration card. This article covers GitLab Self-Hosted, for a self-managed instance whether cloud-hosted or on-prem. It works at the instance level and can additionally create, block, and delete users. To connect a GitLab.com group with a token, use GitLab (Token). To authorize in the browser instead, use GitLab (OAuth).

​
After this article

You will be able to connect a self-managed GitLab instance to Lumos to sync users, groups, group roles, projects, and project roles, then provision, deprovision, and review that access from Lumos.

​
Capabilities

Because this connector works at the instance level, it can also create, block, and delete users directly on the instance.

​
Activity Tracking

Status: Supported for billable members only. Billable members are counted in your GitLab subscription. Lumos tracks last activity date (last_activity_on) and last login date (last_login_at). Non-billable members (free-tier, guest users) have no activity data through this integration.

​
Required plan and roles

  • GitLab role: ensure you are an admin and owner in GitLab before you start. You must be an administrator to create a token usable by Lumos.
  • Token type: a personal access token or a group access token, each with the api scope for full functionality. For a group access token, make sure it has access to the parent group you supply during setup.
  • Base URL: the connection requires your instance’s Account Base URL, including the schema.

​
Read-only access vs provisioning

Is read-only possible? No. GitLab Self-Hosted authenticates with a personal or group access token that requires the api scope for full functionality, and no narrower read-only scope is described for this instance-level connector. What full provisioning requires. A personal access token or group access token with the api scope, created by a GitLab administrator, plus your instance’s Account Base URL. Follow the steps below. A group access token must additionally have access to the parent group you supply during setup. Watch out for. Because this connector works at the instance level, it can also create, block, and delete users directly on the instance, in addition to the group- and project-level actions available on the GitLab.com connectors. Custom member role sync still requires GitLab Ultimate, and activity tracking only covers billable members.

​
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, then copy the token value.
Phase 2: Connect in Lumos
  1. For on-prem, make sure the GitLab Self-Hosted integration is available, then follow the steps in the Lumos UI.
  2. Find the GitLab Self-Hosted card in your Lumos integrations (reconnect an existing card or add a new one).
  3. Fill in the connection fields:
    • Account Base URL: the unique identifier for your GitLab instance. Copy it from the browser while logged in. A correct base URL looks like https://gitlab.<your-organization>.com or an IP address such as http://192.168.1.100:8080. Include the schema (https:// or http://). Port numbers and a base path are supported.
    • GitLab Token: the personal access token or group access token from Phase 1. The api scope is required in both cases.
    • Parent Group: the parent group slug to scope this connector instance to. This is the slug that appears in GitLab URLs. For example, 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. This connector instance only has access to subgroups and projects nested under this parent group.
    • Sync only billable users: by default Lumos fetches all users. Check this option to sync only billable users.
  4. Complete the connection.

​
API Endpoints Used

​
Troubleshooting

Can’t connect the integration. Confirm the Account Base URL includes the schema (https:// or http://) and points at your instance, and that the token carries the api scope. For a group access token, verify it has access to the parent group you entered. Only some users appear. By default Lumos fetches all users. If “Sync only billable users” is checked, non-billable users are excluded by design. No activity data for some users. Activity tracking covers billable members only. Free-tier and guest users have no activity data. Connecting hangs and then errors. Usually the instance base URL is unreachable from Lumos (behind Zscaler, a VPN, or IP restrictions), so the request silently times out and surfaces as a generic error after a delay. Allowlist the Lumos outbound IP addresses (see the Lumos IP addresses Help Center article) so Lumos can reach your GitLab instance.