Skip to main content

GitLab Connector

The GitLab connector ingests data from a GitLab instance into the Context 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​

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, the webhook endpoint is not registered.

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 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 project item is still emitted with an empty project_languages object.

Webhook mode​

EventEmits
Pipeline Hookproject + pipeline (only the data types present in the mapping)
Push Hookproject

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​