Skip to main content
Version: 15.2.1

GitLab Connector

The GitLab connector ingests data from a GitLab instance into the Catalog. It runs through the ibdm binary in one of two modes:

  • Sync — pull-based: queries the GitLab REST API and exits.
  • Run — push-based: exposes a webhook endpoint that receives GitLab events.

Both GitLab.com and self-hosted instances are supported through GITLAB_BASE_URL.

Commands​

ibdm sync gitlab --include-internal-mappings=all
ibdm run gitlab --include-internal-mappings=all

The commands use every internal mapping of the source. To select only some of them, or to add mappings of your own, see Mappings.

Configuration​

VariableRequiredDefaultDescription
GITLAB_TOKENYes(empty)Personal, project, or group access token used for REST API requests.
GITLAB_BASE_URLYes(empty)Base URL of the GitLab instance (e.g. https://gitlab.com).
GITLAB_WEBHOOK_PATHNo/gitlab/webhookHTTP path for inbound webhook events.
GITLAB_WEBHOOK_TOKENRun(empty)Secret used to validate the X-Gitlab-Token header on inbound webhooks. If unset, ibdm run gitlab fails to start.

Authentication​

The source sends GITLAB_TOKEN as the PRIVATE-TOKEN header on every request. The token must have read permissions on the projects, pipelines, and access tokens you intend to synchronize.

Supported data types​

TypeSyncWebhook
project✅✅
pipeline✅✅
accesstoken✅—

Sync mode​

project is the primary resource. When a mapping of type project is used, such as the internal projects, ibdm iterates over all accessible projects and, for each one, optionally fetches:

  • project access tokens, when a mapping of type accesstoken is also used;
  • project pipelines, when a mapping of type pipeline is also used.

When a mapping of type accesstoken is used, ibdm additionally iterates over all accessible groups and fetches their group-level access tokens.

Each project item includes a project_languages field containing the language usage breakdown for that project, enriched via GET /api/v4/projects/{id}/languages. The value is a JSON object mapping each language name to its percentage share:

{ "Go": 97.50, "Makefile": 2.43, "Dockerfile": 0.07 }

If the languages call fails, the sync run aborts entirely for that project (and thus the whole sync) rather than emitting the item without project_languages.

Webhook mode​

EventEmits
Pipeline Hookproject + pipeline, only when mappings of both types are used: with projects or pipelines alone, a Pipeline Hook writes nothing
Push Hookproject

Both webhook event types also populate project_languages on project items, using the same enrichment call as sync mode.

Internal mappings​

ibdm mappings list gitlab prints the internal mappings of this source, and the Internal Mappings reference lists the Item Type each one writes.

Internal mappingTypeSyncWebhook
projectsproject✅✅
pipelinespipeline✅ while the projects are walked✅ together with projects
accesstokensaccesstoken✅—

Pipelines are only fetched while the projects are walked, so selecting pipelines alone produces nothing: select it together with projects, for example:

ibdm sync gitlab --include-internal-mappings=projects,pipelines

See also​