GitLab Plugin Configuration Guide

This guide explains how to configure the ActivityPulse GitLab plugin to fetch activity data from your GitLab instance.

Prerequisites

GitLab account with access to projects you want to track
Personal Access Token with appropriate scopes
GitLab instance URL (gitlab.com or self-hosted)

Overview

The GitLab plugin uses the GitLab REST API to fetch activity data. This requires:

GitLab URL - The base URL of your GitLab instance
Personal Access Token - A PAT with read access to the API

Step 1: Create a Personal Access Token

1.1 Navigate to Access Tokens

Log in to your GitLab instance
Click your avatar in the top-right corner
Select Edit profile
In the left sidebar, click Access Tokens

1.2 Create New Token

Enter a Token name (e.g., ActivityPulse)
Set an Expiration date (recommended: 1 year)
Select the following scopes:

Scope	Purpose
`read_api`	Read access to the API (required)
`read_user`	Read user information

Click Create personal access token

1.3 Copy the Token

IMPORTANT: Copy the token immediately. You will NOT be able to see it again.

Store it securely - you’ll need it for ActivityPulse configuration.

Step 2: Configure ActivityPulse

2.1 Enter Configuration in ActivityPulse

In the ActivityPulse web interface:

Navigate to Data Sources
Click Add Data Source or edit an existing GitLab source
Enter the values:

Field	Value	Example
GitLab URL	Base URL of your GitLab instance	`https://gitlab.com`
API Token	Personal Access Token from Step 1	`glpat-xxxxx`
Jira URL (Optional)	Jira instance for issue linking	`https://company.atlassian.net`
Completed-item lookback (days)	How far back to look for merged/closed work	`30` (default)

Click Save Configuration

2.2 Completed-item lookback

ActivityPulse takes a daily snapshot of the merge requests and issues currently assigned to each teammate. A snapshot of open work alone cannot tell you what finished: an item that stops appearing might have been merged, reassigned, unassigned — or simply missed by a failed sync.

This setting is how long a completion stays visible to the sync. Each run also asks GitLab for merge requests merged and issues closed within the last N days, so a completion is recorded from what GitLab actually reports rather than guessed from an item’s absence.

Defaults to 30 days, accepts 0–90.
It only has to exceed your sync interval, not the longest period you report on. Once a completion is captured in any snapshot it stays on the item. 30 days covers a weekly sync with a wide margin.
Set it to 0 to switch the extra queries off. Completions are then never observed, so finished items stop being labeled as resolved and simply show the last state that was seen, dated. Only worth doing if you are working around a rate-limit problem.
Raising it costs one extra request per teammate per sync per 100 completed items, so a larger window is mainly a cost question.

The configuration dialog includes a toggle labelled “Use as issue management system”. It controls whether this provider’s plugin pages — such as Issue Hierarchy, Worklog, and Value Stream for the providers that surface them — appear in the sidebar.

Defaults to on, so new and existing configurations behave as before.
For GitLab the toggle gates the three GitLab plugin pages — Issue Hierarchy, Worklog, and Value Stream (described under “GitLab Plugin Pages” below). When it is on all three appear in the sidebar; when off none do.
The toggle is a sidebar-visibility convenience only, not a server-side access boundary — the pages remain reachable by direct URL whatever the setting, because any viewer-role user is already entitled to the underlying data.
Turning it off does not affect data sync — only sidebar visibility.

2.4 Map Users

For each team member you want to track:

Navigate to Teammates
Edit the team member
In the External IDs section, add their GitLab identifier
Enter their GitLab username (e.g., johndoe)

Data Collected

The GitLab plugin collects the following activity data:

Merge Requests

MRs created, merged, and reviewed
Review comments and approvals
Time spent on code reviews

Commits

Commits pushed to repositories
Commit messages and timestamps
Lines added/removed

Issues

Issues created and closed
Issue comments
Time tracking entries

Pipelines

Pipeline runs triggered
Pipeline status and duration

Verification

Test the Connection

In ActivityPulse, go to Data Sources
Find your GitLab data source
Click Test Connection
A successful test confirms the API token is valid

Verify Data Collection

Click Fetch to trigger immediate data collection
Go to Activities to see fetched activity data
Filter by source type “GitLab” to see only GitLab activities

Troubleshooting

”Authentication failed” Error

Verify the API token is copied correctly (no leading/trailing spaces)
Ensure the token hasn’t expired
Check that the token has the required scopes (read_api)

“Not found” Errors

Verify the GitLab URL is correct and accessible
Check if the URL requires a /api/v4 suffix (ActivityPulse adds this automatically)
For self-hosted instances, ensure the API is enabled

No Data After Fetch

Verify team members have GitLab external IDs configured
Ensure the API token owner has access to the relevant projects
Check that users have recent activity in the configured date range

Rate Limiting

GitLab limits API calls (varies by instance)
ActivityPulse handles rate limiting automatically with retries
If persistent, reduce sync frequency or contact your GitLab admin

Jira Integration (Optional)

If you use Jira for issue tracking and reference Jira issues in GitLab:

Set the Jira URL in the GitLab configuration
Jira issue references in branch names (e.g., feature/ABC-123-add-login) will be automatically linked
Jira references in commit messages will also be linked

This allows you to see Jira context directly in your GitLab activities.

Security Best Practices

Token Management

Use dedicated tokens for ActivityPulse (not your personal tokens for other tools)
Set reasonable expiration dates and rotate tokens before expiry
Store tokens securely using a password manager

Minimal Permissions

Only grant read_api and read_user scopes
Do not grant write permissions unless specifically needed

Self-Hosted Instances

Ensure your GitLab instance uses HTTPS
Consider IP allowlisting if your GitLab supports it
Monitor token usage in GitLab’s access logs

API Permissions Reference

read_api

Grants access to:

User activity feeds
Project information
Merge request data
Issue data
Pipeline information

read_user

Grants access to:

User profile information
Email addresses (for matching users)

GitLab Plugin Pages

When GitLab is configured and Use as issue manager is enabled (the default), three GitLab-specific pages appear in the ActivityPulse sidebar:

GitLab Worklog

Lists each time-tracking entry your team logged in the selected period. Every /spend action becomes one row showing who logged the time, on which issue or merge request, how much, and the day it was logged. The per-day chart and daily-breakdown table reflect the actual day the time was logged, and totals are the time logged in the period (corrections made with /spend -1h are netted out).

These per-entry details come from GitLab’s GraphQL time-tracking API, which is available on GitLab.com and recent self-managed versions.

Older self-managed GitLab. On instances that do not expose the GraphQL time-tracking query, the page automatically falls back to GitLab’s cumulative time_stats: each row then shows one (teammate, issue or MR) pair with the issue’s running total time spent (summed across the issue’s lifetime, attributed to the teammate’s most recent sync) rather than per-day deltas. The daily-breakdown table buckets those fallback entries by the sync day rather than the actual /spend day.

GitLab Issue Hierarchy

A flat indented view of issues grouped under their milestone (or a synthetic “Unassigned” bucket when an issue has no milestone). The search form takes a project path with optional milestone-title substring and label-CSV filters, plus a State selector.

The State selector defaults to Open, so a long-lived project with a large backlog of closed issues stays fast to load — only its open issues are fetched. Switch it to Closed or All when you need to see resolved issues (for example, to review a completed milestone).

The Estimate and Time Logged columns show each issue’s GitLab time-tracking totals. A milestone row shows the sum (Σ) of the issues rendered beneath it, so narrowing the filter narrows the total too. An empty cell means GitLab holds no value: GitLab records an unset estimate as 0, and ActivityPulse renders that as blank rather than 0m, because an unestimated issue and a zero-effort one are different things.

Why this Time Logged can differ from the Worklog and Value Stream pages. The hierarchy reads GitLab’s own running time_stats total for the issue — every /spend ever recorded against it, by anyone. The Worklog and Value Stream pages instead sum the individual time-tracking entries ActivityPulse has collected, which only covers the periods it has synced. The two agree once collection spans the issue’s whole history and diverge before that; neither is wrong.

Limitations. The current build only ships milestone-based hierarchy, which works on every GitLab tier including Free self-hosted. Full Epic-based hierarchy (Premium / SaaS) and Work Items GraphQL integration are deferred to a follow-up — the existing table already supports arbitrary depth, so the upgrade will not require a frontend rewrite.

GitLab Value Stream

Select one or more GitLab issues (either by milestone/label filter or by pasting {project_path}#{iid} keys), then render a flat per-issue timeline showing every tracked activity (commits, MR events, comments, worklog snapshots). Useful for retracing how a piece of work moved through the system.

Limitations. This view shows the raw timeline; cycle-time phase visualizations (the lane-based dashboard the Atlassian Value Stream page renders) are not yet available for GitLab. The LLM share-summary buttons are likewise not yet exposed — those require the value-stream LLM formatter that Atlassian uses and that the GitLab plugin does not yet ship.

Toggle Gate

The “Use as issue management system” switch in the GitLab data source configuration controls whether the three pages above appear in the sidebar — not whether they can be reached. It is a sidebar-visibility convenience only, not a server-side access boundary: the pages stay reachable by direct URL whatever the setting, because any viewer-role user is already entitled to the underlying data. Set it to off for organizations that use GitLab purely as a code-hosting backend (where Jira or Azure DevOps owns issue management) so the sidebar stays focused.