GitLab
Connector maturity: Beta. See Connector maturity.
Description
The GitLab connector reads the names of the CI/CD variables stored in GitLab (gitlab.com or a self-managed instance) through the GitLab REST API v4, so credentials that live in pipelines instead of your vault can be found. It reads variables of the groups and projects the access token can manage. It does not scan GitLab's users or groups.
Each group or project that has at least one variable appears as a Non-Human account named gitlab-ci:<full path> (for example gitlab-ci:acme/payments/api), holding its variables as CI/CD secret credentials. The variables are also compared with your vault on the Secrets Outside Vault page, and the credential KRIs and credential policy rules apply to them.
System Type Classification
| Field | Value |
|---|---|
| System Type | Application |
| Default Scan Priority | 500 |
Version Support
| OrbisID Edition | Supported |
|---|---|
| Community | No |
| Pro | Yes |
| Enterprise | Yes |
Supported Protocol
| Protocol | Port | Notes |
|---|---|---|
| REST API (HTTPS) | 443 TCP | An access token in the PRIVATE-TOKEN header |
What OrbisID Discovers
| Data | Source |
|---|---|
| Groups the token owns | GET /groups?min_access_level=50 |
| Group CI/CD variables | GET /groups/:id/variables |
| Projects the token maintains | GET /projects?membership=true&min_access_level=40 |
| Project CI/CD variables | GET /projects/:id/variables |
By default only the variables GitLab itself treats as sensitive are reported: masked, hidden or protected variables, and file variables (often keys or certificates). Plain configuration such as NODE_ENV is not counted as a secret. Turn on the system attribute Include Plain Variables (gitlabIncludeAllVariables) to report every variable. A secret that is neither masked, protected nor a file is therefore missed unless you turn it on.
For each variable OrbisID keeps its name and environment scope only. The same name set for two environment scopes is two credentials. GitLab returns each variable's value in this list, and has no created or updated date for a variable. OrbisID discards the value as soon as the response is read and never stores or logs it, and the dates are shown as unknown, not as never. Because the list includes values, give OrbisID a dedicated token and treat it like any other credential that can read secrets.
At most 2,000 projects are read. A group or project whose variables cannot be read (for example because the token lost its role there) is skipped with a warning, and variables already recorded are kept rather than removed.
Connection Requirements
Required Permissions
Create an access token for OrbisID (a group access token, or a personal access token of a dedicated user) with:
- the
read_apiscope - the Owner role on the groups whose variables you want read (GitLab shows group variables to Owners only)
- the Maintainer role or higher on the projects whose variables you want read
A token without these roles sees empty lists rather than an error. If it can see no group it owns and no project it maintains, the scan fails with a message saying so, instead of reporting that no secrets exist.
Credential Mapping
| OrbisID Field | Value |
|---|---|
credential.password | The access token (the username is not used) |
system.hostname | The GitLab host (for example gitlab.com) |
system.pamPlatformUrl | Optional. A full URL for a self-managed instance with a path or non-standard port, for example https://example.com/gitlab |
Network Requirements
The OrbisID server, or the On-Premise Agent for a self-managed instance, must have HTTPS access to the GitLab host on port 443 (or the port you set).
Configuration Steps
- In GitLab create the access token described above
- Create a Credential in OrbisID with the token as the Password
- Navigate to Systems → Add System
- Fill in the fields:
| Field | Value |
|---|---|
| Name | Descriptive name (for example GitLab - acme) |
| OS Type | GitLab |
| System Type | Application |
| Hostname | gitlab.com, or your self-managed host |
| Credential | The access token credential |
- Click Test Connection
- Click Save
Troubleshooting
| Symptom | Likely Cause | Resolution |
|---|---|---|
Authentication failed - check the GitLab access token | The token is wrong, expired or revoked | Create a new token and update the credential |
The token can see no group it owns and no project it maintains | The token has no Owner or Maintainer role anywhere | Give the token's user or group the role, or use another token |
GitLab refused ... (403) | The token lacks the read_api scope | Create a token with the scope |
| Warnings that some variables were not read | The token cannot read those groups or projects | Grant the role there, or accept that they are not covered |
GitLab is throttling requests (429) | A large instance and the API rate limit | The scan can be retried; spread scans out |
| Variables appear without dates | GitLab does not report dates for variables | Expected |