GitLab Integration

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

Why it matters

GitLab is the source for your merge request and commit metrics in Span. A correctly scoped token and the right hostname mean Span sees every group and project you want measured, and nothing you don't.

How it works

• Token-based: Span connects with a GitLab personal access token, or through Guardette, a redacting proxy you run in your own infrastructure.

• Polling, no webhooks: Span pulls data from the GitLab REST API v4 about every 2 hours. You don't need to set up webhooks.

• Incremental: after the first historical sync (6 months by default for a new organization), Span processes only new and changed records.

• Scope follows the token: Span syncs every project the token's user can access, unless Span support has set group or project allowlists for you.

• One GitLab connection per Span organization.

• Rate limits: Span throttles requests to stay within GitLab API limits and retries with backoff when it hits them.

• Squash merges: handled. Span uses the squash commit SHA when there is no standard merge commit.

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

Metrics powered by GitLab

• PR cycle time stages: Coding (first commit to MR opened), Awaiting First Review, Reworking (with Active Coding and Waiting for Review), Idling (last action to merge), and Deploying (merge to production). Deploying needs deployment data sent through Span's DORA API.

• Code review: review cycles, comments authored per week, and reviews per contributor per week.

• Code quality and productivity: lines added and removed, PR size, PRs merged per week, and % of PRs with tests.

Setup

Step 1: Create a personal access token

• GitLab Cloud: gitlab.com/-/profile/personal_access_tokens

• Self-managed: <your-instance-host>/-/profile/personal_access_tokens

Give the token the api scope, as the connection form asks, and create it from a user with read access to every group and project Span should sync. Set an expiry date your team will remember to renew.

Which user should own the token? A personal access token sees exactly what its user can see, and it stops working if that user is blocked or removed. A token from one engineer's account works but ties Span to that person. A dedicated GitLab user for Span, with access to the right groups, keeps the connection running when people change roles.

Step 2: Connect in Span

1. Go to Settings → Integrations and click Connect on the GitLab card.

2. Choose Personal Access Token. (If your security team runs Guardette, choose Guardette — Redacting Proxy and enter your Guardette host and token instead.)

3. Instance Hostname: leave blank for gitlab.com. For self-managed GitLab, enter the hostname only, with no https://, for example gitlab.company.com.

4. Personal Access Token: paste the token (glpat-… or a legacy token).

5. Save. Span checks the token by listing your GitLab groups. If that works, sync starts.

Step 3 (optional): Limit which groups or projects sync

Span support sets group and project allowlists for you. Email support@span.app with the group or project paths you want Span to sync. Without an allowlist, Span syncs every project the token's user can access.

You need the Manage Integrations permission in Span. Owners, Admins, and the Integration Admins group have it by default.

Things to know

• Allowlists are set by Span support. You can't edit them in Span settings. Ask support to add or change them.

• Rotating a token keeps your history. Open the GitLab integration and choose Edit (or Reconnect if the token already failed), then paste the new token. Span updates the same connection, so past data stays. The new token can belong to a different GitLab user, as long as it can see the same groups and projects.

• An expired token pauses sync. Span checks credentials every 6 hours. After two failed checks in a row it pauses the connection and shows Reconnect required. For example, a token that expires Monday at 00:00 could show Reconnect required by about midday Monday. Data catches up after you reconnect.

• People match by GitLab username. Add each person's GitLab username in Settings → People Management (the GitLab Usernames field, shown for Contributors). A person can have more than one.

• PR Revert Rate reads 0 on GitLab. Span detects reverts on github.com only.

• Self-managed instances must be reachable. Span's hosted service connects to your instance. Your network team may need to allow Span's outbound IPs.

Troubleshooting

Related articles

Network Access Requirements

How to create an Integrations Admin in Span

How to use the DORA API to send deployment activity to Span

Supported integrations

Need help?

Contact your Span account team or reach out to support@span.app.