GitLab Connector

The GitLab connector ingests development activity from GitLab into CortexDB as typed episodes. Merge Requests, Issues, Comments, Commits, Pipelines, and Releases are all captured with full metadata and entity relationships.

Setup

1. Create a GitLab Token

Create a personal access token or project/group access token with:

• read_api -- Read access to the API
• read_repository -- Read access to repositories (for commits)

2. Configure the Connector

export CORTEX_GITLAB_URL=https://gitlab.com
export CORTEX_GITLAB_TOKEN=glpat-your-access-token
export CORTEX_GITLAB_PROJECT_IDS=12345,67890
export CORTEX_GITLAB_TENANT_ID=my-app
export CORTEX_GITLAB_NAMESPACE=gitlab

3. Start the Connector

cortexdb-connector gitlab \
  --url https://gitlab.com \
  --token glpat-your-access-token \
  --project-ids "12345,67890" \
  --tenant-id my-app

Or with Docker:

docker run -d \
  --name cortex-gitlab \
  -e CORTEX_GITLAB_URL=https://gitlab.com \
  -e CORTEX_GITLAB_TOKEN=glpat-your-access-token \
  -e CORTEX_GITLAB_PROJECT_IDS=12345,67890 \
  -e CORTEX_GITLAB_TENANT_ID=my-app \
  cortexdb/connector-gitlab:latest

What Gets Ingested

| GitLab Event | Episode Type | Content | |---|---|---| | Merge Request | code_change | Title, description, branches, state | | Issue | issue | Title, description, labels, milestone | | Comment / Note | comment | Comment body with parent context | | Commit | code_change | Commit message and SHA | | Pipeline | deployment | Pipeline status, ref, source | | Release | deployment | Release name, tag, description |

Episode Metadata

{
  "type": "code_change",
  "content": "MR [merged]: Refactor authentication middleware (feature/auth -> main)\nReplace legacy session-based auth with JWT tokens...",
  "source": "gitlab",
  "timestamp": "2026-03-17T15:20:00Z",
  "metadata": {
    "gitlab_event": "merge_request",
    "project": "acme/backend",
    "state": "merged"
  },
  "entities": [
    { "type": "project", "id": "12345", "name": "acme/backend" },
    { "type": "user", "id": "789", "name": "alice" },
    { "type": "label", "id": "enhancement", "name": "enhancement" }
  ]
}

Configuration

| Variable | Default | Description | |---|---|---| | CORTEX_GITLAB_URL | https://gitlab.com | GitLab instance URL | | CORTEX_GITLAB_TOKEN | Required | GitLab access token | | CORTEX_GITLAB_PROJECT_IDS | (none) | Comma-separated project IDs | | CORTEX_GITLAB_GROUP_IDS | (none) | Comma-separated group IDs (syncs all projects) | | CORTEX_GITLAB_EVENTS | merge_request,issue,note,commit,pipeline,release | Comma-separated event types | | CORTEX_GITLAB_TENANT_ID | Required | Target tenant | | CORTEX_GITLAB_NAMESPACE | gitlab | Target namespace | | CORTEX_GITLAB_BACKFILL_DAYS | 90 | Days of history to backfill | | CORTEX_GITLAB_POLL_INTERVAL_SEC | 60 | Polling interval |

Backfill

On first run, the connector backfills events from the last CORTEX_GITLAB_BACKFILL_DAYS days (default 90). Merge requests and issues use the updated_after parameter for incremental sync. Commits use the since parameter. Pipelines use updated_after. Releases are sorted by date with client-side cutoff filtering. All list endpoints use the python-gitlab iterator for automatic pagination. System-generated notes (label changes, assignments) are filtered out.