@relayfile/adapter-gitlab

GitLab adapter for Relayfile. It mirrors the GitHub adapter pattern, but maps GitLab merge requests, discussions, approvals, issues, commits, pipelines, jobs, deployments, and tag pushes into GitLab-specific VFS paths.

Quick start

import { GitLabAdapter } from '@relayfile/adapter-gitlab';

const adapter = new GitLabAdapter(provider, {
  connectionId: 'gitlab-connection',
  projectPath: 'acme/api',
  webhookSecret: process.env.GITLAB_WEBHOOK_SECRET,
});

const result = await adapter.routeWebhook(payload, undefined, headers);

Materialization policy

Bulk project syncs are eager by default. Set materialization.default to lazy and add project rules when a persona or workspace should sync only a subset of GitLab records:

const adapter = new GitLabAdapter(provider, {
  connectionId: 'gitlab-connection',
  projectPath: 'acme/api',
  materialization: {
    default: 'lazy',
    webhookWritesForLazyProjects: true,
    rules: [
      {
        projects: ['acme/*'],
        issues: {
          mode: 'eager',
          filter: { state: 'opened', labels: ['factory'] },
          incremental: true,
        },
        merge_requests: 'lazy',
      },
    ],
  },
});

Rules are first-match, project patterns accept * and ?, and resource modes accept lazy/eager plus legacy aliases none/all. since or incremental: true is applied to GitLab list queries where the resource API supports it.

Supported webhook events

• merge_request.open
• merge_request.reopen
• merge_request.update
• merge_request.close
• merge_request.merge
• merge_request.approved
• merge_request.unapproved
• note.MergeRequest
• note.Issue
• note.Commit
• note.Snippet
• push
• pipeline.created
• pipeline.pending
• pipeline.running
• pipeline.success
• pipeline.failed
• pipeline.canceled
• pipeline.manual
• pipeline.skipped
• pipeline.waiting_for_resource
• issue.open
• issue.reopen
• issue.update
• issue.close
• deployment.created
• deployment.running
• deployment.success
• deployment.failed
• deployment.canceled
• build.created
• build.pending
• build.running
• build.success
• build.failed
• build.canceled
• build.manual
• build.skipped
• job.created
• job.pending
• job.running
• job.success
• job.failed
• job.canceled
• job.manual
• job.skipped
• tag_push

VFS path structure

/gitlab/LAYOUT.md
/gitlab/_index.json
/gitlab/projects/_index.json
/gitlab/projects/{namespace}/{project}/meta.json
/gitlab/projects/{namespace}/{project}/merge_requests/{iid}__{slug}/meta.json
/gitlab/projects/{namespace}/{project}/merge_requests/{iid}__{slug}/diff.patch
/gitlab/projects/{namespace}/{project}/merge_requests/{iid}__{slug}/discussions/{id}.json
/gitlab/projects/{namespace}/{project}/merge_requests/{iid}__{slug}/approvals.json
/gitlab/projects/{namespace}/{project}/merge_requests/by-id/{iid}.json
/gitlab/projects/{namespace}/{project}/merge_requests/by-title/{slug}__{iid}.json
/gitlab/projects/{namespace}/{project}/issues/{iid}__{slug}/meta.json
/gitlab/projects/{namespace}/{project}/issues/{iid}__{slug}/comments/{id}.json
/gitlab/projects/{namespace}/{project}/issues/by-id/{iid}.json
/gitlab/projects/{namespace}/{project}/issues/by-title/{slug}__{iid}.json
/gitlab/projects/{namespace}/{project}/commits/{sha}__{slug}/meta.json
/gitlab/projects/{namespace}/{project}/commits/{sha}__{slug}/comments/{id}.json
/gitlab/projects/{namespace}/{project}/snippets/{id}/comments/{id}.json
/gitlab/projects/{namespace}/{project}/pipelines/{id}__{ref}/meta.json
/gitlab/projects/{namespace}/{project}/pipelines/{id}__{ref}/jobs/{id}.json
/gitlab/projects/{namespace}/{project}/pipelines/by-ref/{ref-slug}__{id}.json
/gitlab/projects/{namespace}/{project}/pipelines/by-status/{status}/{id}.json
/gitlab/projects/{namespace}/{project}/deployments/{id}.json
/gitlab/projects/{namespace}/{project}/deployments/by-status/{status}/{id}.json
/gitlab/projects/{namespace}/{project}/tags/{slug}__{encoded-ref}.json
/gitlab/projects/{namespace}/{project}/tags/by-ref/{ref-slug}__{encoded-ref}.json

Project meta.json files are managed by Cloud syncs and are read-only for writeback.

Writeback paths

File-native writeback uses canonical filenames for updates and any non-canonical ("draft") filename to create new records. new.json has no special runtime meaning — see docs/migration/file-native-writeback.md.

• PUT /gitlab/projects/{namespace}/{project}/merge_requests/{iid}__{slug}/meta.json
• POST /gitlab/projects/{namespace}/{project}/merge_requests/{iid}__{slug}/discussions/<draft>.json
• PUT /gitlab/projects/{namespace}/{project}/issues/{iid}__{slug}/meta.json
• POST /gitlab/projects/{namespace}/{project}/issues/{iid}__{slug}/comments/<draft>.json

Comparison with the GitHub adapter

• GitLab uses path_with_namespace instead of owner/repo.
• Merge requests and issues use iid, not global IDs.
• Reviews map to two GitLab concepts: discussions and approvals.
• GitLab CI maps to pipelines and jobs instead of check suites and check runs.
• Webhook verification uses X-Gitlab-Token, not an HMAC signature.