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:

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

Step 1: Create a Personal Access Token

1.1 Navigate to Access Tokens

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

1.2 Create New Token

  1. Enter a Token name (e.g., ActivityPulse)
  2. Set an Expiration date (recommended: 1 year)
  3. Select the following scopes:
ScopePurpose
read_apiRead access to the API (required)
read_userRead user information
  1. 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:

  1. Navigate to Data Sources
  2. Click Add Data Source or edit an existing GitLab source
  3. Enter the values:
FieldValueExample
GitLab URLBase URL of your GitLab instancehttps://gitlab.com
API TokenPersonal Access Token from Step 1glpat-xxxxx
Jira URL (Optional)Jira instance for issue linkinghttps://company.atlassian.net
  1. Click Save Configuration

2.2 Map Users

For each team member you want to track:

  1. Navigate to Teammates
  2. Edit the team member
  3. In the External IDs section, add their GitLab identifier
  4. 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

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

Verify Data Collection

  1. Click Fetch to trigger immediate data collection
  2. Go to Activities to see fetched activity data
  3. 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:

  1. Set the Jira URL in the GitLab configuration
  2. Jira issue references in branch names (e.g., feature/ABC-123-add-login) will be automatically linked
  3. 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)

Additional Resources