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 --mapping-file <path to mapping file or folder>
ibdm run  gitlab --mapping-file <path to mapping file or folder>

Configuration

Variable	Required	Default	Description
GITLAB_TOKEN	Yes	(empty)	Personal, project, or group access token used for REST API requests.
GITLAB_BASE_URL	Yes	(empty)	Base URL of the GitLab instance (e.g. https://gitlab.com).
GITLAB_WEBHOOK_PATH	No	/gitlab/webhook	HTTP path for inbound webhook events.
GITLAB_WEBHOOK_TOKEN	Run	(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

Type	Sync	Webhook
project	✅	✅
pipeline	✅	✅
accesstoken	✅	—

Sync mode

project is the primary resource. When it appears in the mapping file, ibdm iterates over all accessible projects and, for each one, optionally fetches:

• project access tokens, when accesstoken is also in the mapping;
• project pipelines, when pipeline is also in the mapping.

When accesstoken is in the mapping, 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

Event	Emits
Pipeline Hook	project + pipeline (pipeline is only emitted if project is also in the mapping — a mapping containing only pipeline produces no events at all)
Push Hook	project

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

Example mappings

Reference mapping files live in docs/examples/gitlab/mappings/ of the ibdm repository:

• projects.yaml — map GitLab projects to Catalog items.
• pipelines.yaml — map pipelines to Catalog items.
• accesstokens.yaml — map access tokens to Catalog items.

Pass the file or the folder to --mapping-file:

ibdm sync gitlab --mapping-file docs/examples/gitlab/mappings/

See also

• Connectors Installation Overview