Skip to main content

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​

FieldValue
System TypeApplication
Default Scan Priority500

Version Support​

OrbisID EditionSupported
CommunityNo
ProYes
EnterpriseYes

Supported Protocol​

ProtocolPortNotes
REST API (HTTPS)443 TCPAn access token in the PRIVATE-TOKEN header

What OrbisID Discovers​

DataSource
Groups the token ownsGET /groups?min_access_level=50
Group CI/CD variablesGET /groups/:id/variables
Projects the token maintainsGET /projects?membership=true&min_access_level=40
Project CI/CD variablesGET /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_api scope
  • 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 FieldValue
credential.passwordThe access token (the username is not used)
system.hostnameThe GitLab host (for example gitlab.com)
system.pamPlatformUrlOptional. 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​

  1. In GitLab create the access token described above
  2. Create a Credential in OrbisID with the token as the Password
  3. Navigate to Systems → Add System
  4. Fill in the fields:
FieldValue
NameDescriptive name (for example GitLab - acme)
OS TypeGitLab
System TypeApplication
Hostnamegitlab.com, or your self-managed host
CredentialThe access token credential
  1. Click Test Connection
  2. Click Save

Troubleshooting​

SymptomLikely CauseResolution
Authentication failed - check the GitLab access tokenThe token is wrong, expired or revokedCreate a new token and update the credential
The token can see no group it owns and no project it maintainsThe token has no Owner or Maintainer role anywhereGive the token's user or group the role, or use another token
GitLab refused ... (403)The token lacks the read_api scopeCreate a token with the scope
Warnings that some variables were not readThe token cannot read those groups or projectsGrant the role there, or accept that they are not covered
GitLab is throttling requests (429)A large instance and the API rate limitThe scan can be retried; spread scans out
Variables appear without datesGitLab does not report dates for variablesExpected