GitLab Integration

Last updated: April 29, 2026

Overview

Span's GitLab integration syncs merge requests, commits, and repository activity to power code review, cycle time, and developer productivity metrics. Both GitLab Cloud (gitlab.com) and self-hosted GitLab instances are supported.

Setup

Step 1 — Generate a Personal Access Token (PAT)

Your token must have read access to:

  • Groups

  • Projects

  • Merge Requests

  • Discussions / Notes (comments and reviews)

Step 2 — Connect in Span

  1. Navigate to Organization Settings → Integrations → GitLab

  2. Enter your Personal Access Token

  3. (Self-hosted only) Enter your Host URL — defaults to gitlab.com

  4. Save. Span will validate credentials by attempting to fetch groups from your account. If successful, sync begins automatically.

Step 3 — (Optional) Filter Repositories

You can restrict which data is synced by configuring allowlists:

  • Group allowlist — sync only from specific GitLab groups

  • Project allowlist — sync only from specific GitLab projects

If no filters are set, Span syncs all projects accessible to the authenticated user.

What Data Is Ingested

GitLab Data

Span Asset

Merge Requests

Pull Requests

MR Notes / Discussions

PR Comments & Reviews

MR Commits

Commits

MR Diffs

PR Diffs

Project Events

Repository Activity

Projects

Repositories

Sync is incremental — after the initial historical sync, only new and changed records are processed.

Not ingested: Direct push events, branches, GitLab Issues, wikis, or other non-code content.

Metrics Powered by This Integration

GitLab data feeds directly into Span's core engineering metrics:

PR Cycle Time Breakdown

  1. Coding — First commit → PR opened

  2. Awaiting First Review — PR opened → First review received

  3. Reworking — First review → Last action (with Active Coding vs. Waiting for Review sub-breakdown)

  4. Idling — Last action → Merged

  5. Deploying — Merged → In production (requires a deployment integration)

Code Review Metrics

  • Review cycles (back-and-forth exchanges)

  • Comments authored per week

  • Reviews per contributor per week

Code Quality & Productivity Metrics

  • Lines added / removed

  • PR size and revert rate

  • PRs merged per week

  • Test coverage (% of PRs with tests)

Configuration Reference

Setting

Description

Personal Access Token

Authentication credential (encrypted at rest, never displayed after entry)

Host URL

Self-hosted GitLab instance URL (optional; defaults to gitlab.com)

Group Allowlist

Restrict sync to specific GitLab groups

Project Allowlist

Restrict sync to specific GitLab projects

Start Date

Historical sync start point

Sync Behavior

  • Method: Polling-based — Span periodically fetches data from the GitLab API. Webhook setup is not required.

  • Rate limiting: Span throttles requests per the GitLab API limits. If limits are exceeded, it automatically retries with backoff.

  • Squash merges: Correctly handled — Span uses the squash commit SHA when a standard merge commit SHA is unavailable.

Updating the Integration

You can edit the integration at any time to:

  • Rotate or replace an expired PAT

  • Change the host URL (for self-hosted migrations)

  • Update group/project allowlists

Supported Platforms

Platform

Support

GitLab Cloud (gitlab.com)

✅ Fully supported

Self-Hosted GitLab

✅ Supported via custom host URL

Required API

GitLab REST API v4

Troubleshooting

Symptom

Likely Cause

Resolution

Connection validation fails

Invalid PAT or insufficient scopes

Regenerate the token with the required read scopes

Data stops syncing

PAT expired

Update the token in Integration Settings

Missing repositories

Group/project filter too restrictive

Review your allowlist configuration

Slow or delayed data

GitLab API rate limiting

Span will auto-retry; no action needed unless persistent

Need help? Contact Span support through your dashboard for questions about self-hosted compatibility or account-specific issues.