GitLab Connector
Ingest GitLab issues, merge requests, and notes into CortexDB.
Tails GitLab issues, merge requests, and their notes (comments) and writes them to CortexDB as experiences.
Two ways to run this connector
Self-hosted — pip install 'cortexdb-connectors[gitlab]' then cortexdb-sync sync gitlab.
Managed — CortexDB runs the connector as a worker. See the Connectors overview.
1. Prepare credentials
GitLab → Preferences → Access Tokens → create a personal (or project) access token with the read_api
scope, and copy it.
What gets written
Each issue, merge request, and note becomes a POST /v1/experience on the resolved scope (default
org:<org>/source:gitlab/project:{project}), author resolved to a username, body as content.
Record keys and threads
- The
idempotency_keyismr:{project_id}:{id},issue:{project_id}:{id}, ornote:{project_id}:{parent_type}:{parent_iid}:{id}— there is nogl:prefix, and segments are separated by:(not thegl:<type>:<project_id>/<id>the older docs showed). - Merge-request note linkage is a
thread=…label, notcontext.preceded_by.
The key on the wire is derived
The key format above is this connector's internal record identity: it decides which source record an
event belongs to. The idempotency_key actually sent to CortexDB is a derived cxsrc:<56 hex> value
that also hashes the content, labels, observed time and actor, so an unchanged redelivery converges on
the same event while any edit lands as a new one, even where the key format itself is not
content-versioned. Every event also carries a source descriptor with the record's fingerprint. See
Source identity and keys.
Run it yourself
pip install 'cortexdb-connectors[gitlab]'
pip install cortexdb-cli && cortexdb init
export GITLAB_TOKEN=glpat-... # required
cortexdb-sync --api-url http://localhost:3141 sync gitlab
cortexdb-sync --api-url http://localhost:3141 watch gitlab --interval 120For a self-managed GitLab instance, set GITLAB_URL (below). Cursor state persists in ~/.cortexdb/sync_state.json.
Optional settings
Set these as environment variables (or the matching keys in the cortexdb-sync YAML config). Lists are comma-separated. For on/off settings, 1, true, yes or on turns the setting on and any other value turns it off.
| Setting | What it does | Default |
|---|---|---|
GITLAB_URL | Base URL of your GitLab (set it for a self-managed instance) | https://gitlab.com |
GITLAB_PROJECT_IDS | Numeric project IDs to sync | None |
GITLAB_GROUP_IDS | Numeric group IDs; every project in the group and its subgroups is synced | None |
GITLAB_EVENTS | Event types to sync | merge_request, issue, note, commit, pipeline, release |
Set GITLAB_PROJECT_IDS or GITLAB_GROUP_IDS: with neither, there is nothing to sync.