GitLab Automatic Integration

Nexus Docs includes a GitLab webhook endpoint that can trigger the documentation refresh pipeline when content changes land in GitLab.

The current implementation is event-driven:

GitLab sends a push or merge request webhook to Nexus Docs.
Nexus Docs validates the X-Gitlab-Token header against WEBHOOK_SECRET.
A content-sync queue job is created.
The worker scans CONTENT_DIR for changed Markdown and MDX files.
Changed files are recorded in ContentRevision.
The worker calls /api/cache/invalidate.
If anything changed, a search reindex job is queued.

Important distinction

The webhook route does not pull GitLab content by itself. It triggers the worker pipeline. Your deployment still needs the content files available in CONTENT_DIR, usually by mounting a checked-out content repository or running a sync step before the worker scans.

Required services

GitLab automation needs the worker queue stack:

Service	Why it is needed
App	Receives `/api/webhooks/gitlab` and invalidates the content cache.
Worker	Runs `content-sync` and chains reindexing.
Redis	BullMQ queue backend used by the app and worker.
Database	Stores audit log entries and content revision records.
MeiliSearch	Optional for rendering, required if you want automatic search refresh.

If you run Nexus Docs without Redis or the worker, GitLab webhooks cannot process background sync jobs.

Environment variables

env

WEBHOOK_SECRET=generate-with-openssl-rand-base64-32
CONTENT_DIR=/app/content

GITLAB_URL=https://gitlab.com
GITLAB_TOKEN=
GITLAB_CONTENT_PROJECT_ID=
GITLAB_CONTENT_BRANCH=main

Variable	Purpose
`WEBHOOK_SECRET`	Shared secret used to validate GitLab webhook requests.
`CONTENT_DIR`	Directory that Nexus Docs scans for `.md` and `.mdx` files.
`GITLAB_URL`	GitLab instance URL. Defaults to `https://gitlab.com`.
`GITLAB_TOKEN`	Private token used by GitLab helper APIs and optional sync scripts.
`GITLAB_CONTENT_PROJECT_ID`	Project ID for issue creation and content repository operations.
`GITLAB_CONTENT_BRANCH`	Branch that should trigger sync. Defaults to `main`.

GitLab webhook setup

In GitLab, create a project webhook:

Text

URL:    https://docs.example.com/api/webhooks/gitlab
Secret: same value as WEBHOOK_SECRET
Events: Push events, Merge request events

Nexus Docs reacts to:

GitLab event	Condition	Action
Push Hook	`ref` equals `refs/heads/<GITLAB_CONTENT_BRANCH>`	Enqueue incremental content sync.
Merge Request Hook	MR state is `merged` and target branch equals `GITLAB_CONTENT_BRANCH`	Enqueue full content sync.

Other events are acknowledged but do not trigger a sync.

Deployment pattern

A common production pattern is:

Text

GitLab repository
  -> push or merged MR
  -> GitLab webhook
  -> Nexus Docs app
  -> Redis queue
  -> Nexus Docs worker
  -> scan CONTENT_DIR
  -> invalidate cache
  -> reindex search

For Docker deployments, mount the content repository into both app and worker:

YAML

services:
  app:
    volumes:
      - ./content:/app/content:ro

  worker:
    volumes:
      - ./content:/app/content

Then make sure your deploy or sync process updates ./content before or alongside the webhook-triggered scan.

Manual sync command

The repository also includes a helper script:

Bash

docker compose exec worker bash scripts/content-sync.sh

The script can inspect local content and contains a GitLab configuration path. Treat it as an operational helper, not as the primary runtime webhook flow.

Issue creation

When users report documentation issues, Nexus Docs can create GitLab issues if GITLAB_TOKEN and GITLAB_CONTENT_PROJECT_ID are configured.

That path is separate from automatic content sync:

Issue reporting uses GitLab API helpers.
Content refresh uses GitLab webhooks plus worker jobs.

Troubleshooting

Symptom	Check
Webhook returns `500`	`WEBHOOK_SECRET` is missing.
Webhook returns `401`	GitLab secret token does not match `WEBHOOK_SECRET`.
Webhook returns `200` but content does not change	Worker, Redis, or `CONTENT_DIR` is not configured correctly.
Content changes but search is stale	Worker could not reach MeiliSearch, or reindexing failed.
Sync works manually but not from GitLab	Confirm webhook events are enabled and branch matches `GITLAB_CONTENT_BRANCH`.