Skip to main content

​
GitLab Repository Integration

​
Overview

The GitLab Repository Integration allows Engineering Metrics to connect with GitLab repositories and collect repository-level engineering data for analytics, reporting, and project tracking. Using this integration, users can:
  • Connect GitLab Cloud or GitLab Server instances
  • Authenticate using a Personal Access Token (PAT)
  • Add repositories as Data Scopes
  • Associate repositories with projects and scope configurations
  • Enable repository-level analytics within Engineering Metrics
To access GitLab integrations:
  1. Open the Engineering Metrics platform.
  2. Navigate to Integration → Data Integrations Hub.
  3. Under Repository Integrations, locate GitLab.
  4. Click:
    • Connect if no connection exists.
    • Manage if an existing connection is already configured.
The GitLab card displays:
  • Connection status
  • Available integration actions
  • Current connection state

​
GitLab Connection Setup

​
Creating a New GitLab Connection

Inside the GitLab Connections page:
  1. Click New Connection.
  2. The Manage Connections: GitLab configuration modal will open.

​
Connection Configuration Fields

​
Connection Name

Field: Connection Name Purpose Provides a unique identifier for the GitLab connection. Examples
  • GitLab Production
  • GitLab Engineering Team
  • Internal GitLab Server
Recommendation Use a descriptive name to distinguish between multiple GitLab environments.

​
GitLab Type Selection

Users can choose between the following options.

​
GitLab Cloud

Use this option when connecting to GitLab Cloud.
Important: When GitLab Cloud is selected, the endpoint URL is automatically handled by the system.
Default API Endpoint 
https://gitlab.com/api/v4/

​
GitLab Server (v11+)

Use this option for self-hosted GitLab instances running version 11 or higher.
Note: Self-hosted environments may require additional network accessibility and authentication validation.

​
Personal Access Token (PAT)

Field: Personal Access Token Purpose Used to authenticate Engineering Metrics with GitLab. Requirements
  • A valid GitLab Personal Access Token must be generated beforehand.
  • The token must have sufficient permissions to access repositories and repository metadata.
Input Example 
glpat-xxxxxxxxxxxx
Important:
  • Tokens are securely stored.
  • Ensure the token has not expired.
  • Revoked or invalid tokens may cause synchronization failures.

​
Proxy Configuration

Field: Proxy Purpose Allows routing requests through a proxy server if GitLab cannot be accessed directly. Example 
http://proxy.localhost:8080
Use Cases
  • Enterprise firewall restrictions
  • Internal networking policies
  • Restricted outbound internet access
If no proxy is required, this field can be left empty.

​
Custom Rate Limit

Option: Custom Rate Limit Toggle Purpose Allows users to manually control GitLab API collection speed. Default Behavior Engineering Metrics uses dynamic rate limiting for optimized data collection. When Enabled Users can configure a fixed rate limit value. Typical Use Cases
  • Preventing API throttling
  • Managing load on self-hosted GitLab servers
  • Controlling synchronization speed

​
Testing the Connection

Before saving the connection:
  1. Click Test Connection.

​
Expected Result

The platform validates:
  • GitLab accessibility
  • Token authentication
  • API communication
If validation succeeds, the connection is ready to be saved.

​
Potential Failure Reasons

  • Invalid Personal Access Token
  • Incorrect proxy configuration
  • Network restrictions
  • GitLab server unavailability

​
Saving the Connection

After successful validation:
  1. Click Save Connection.

​
Result

The GitLab integration becomes available in the Connections panel. The connection status should display as: 
Connected

​
Managing Existing Connections

Inside the GitLab Connections page, users can:
  • View all configured GitLab connections
  • Search existing connections
  • Select active connections
  • Manage repository scopes associated with each connection
The left panel displays:
  • Connection name
  • Connection entries
  • Total configured connections

​
Adding a Data Scope

Data Scopes define which repositories Engineering Metrics will collect data from.

​
Steps to Add a Data Scope

  1. Select the desired GitLab connection.
  2. Click Add Data Scope.
  3. The Add Data Scope modal opens.

​
Repository Selection

Inside the Add Data Scope window, users can:
  • Search repositories by repository name
  • Browse available repositories
  • Select one or more repositories for integration
Displayed Repository Information
  • Repository Name
  • Organization
  • Last Updated Timestamp

​
Selecting Repositories

  1. Use the checkbox beside the repository name.
  2. Select the repositories to include.
  3. Click Add Scopes.

​
Result

Selected repositories are added to the integration scope for analytics and synchronization.

​
Scope Association and Project Mapping

After adding repositories, the selected repositories appear in the Data Scope table.

​
Displayed Information

  • Data Scope
  • Project
  • Scope Config
  • Actions
Users can associate:
  • Projects
  • Scope Configurations
  • Repository Mappings
This enables Engineering Metrics to organize collected repository data under the correct project context.

​
Search and Filtering

The GitLab integration page includes search functionality for:
  • Searching connections
  • Searching repository scopes
This helps users manage large-scale repository integrations efficiently.

​
Connection Status Indicators

The platform visually displays integration status.

​
Possible Statuses

  • Connected
  • Not Connected
Connected integrations display a successful connection indicator on the GitLab integration card.

​
Best Practices

​
Use Dedicated Service Accounts

Recommended Use a dedicated GitLab service account instead of personal user credentials. Benefits
  • Improved security
  • Easier credential rotation
  • Reduced dependency on individual users

​
Use Descriptive Connection Names

Recommended Naming Examples
  • GitLab Prod
  • GitLab Internal
  • Engineering GitLab EU
This improves maintainability when multiple integrations exist.

​
Limit Repository Scope

Only add repositories that are required for analytics. Benefits
  • Faster synchronization
  • Reduced API usage
  • Improved dashboard performance

​
Regularly Validate Tokens

Expired or revoked PAT tokens may interrupt synchronization. Recommendation Review token validity periodically.

​
Troubleshooting

​
Connection Test Fails

Possible Causes
  • Invalid PAT token
  • GitLab API inaccessible
  • Proxy misconfiguration
  • Network restrictions
Resolution
  • Verify token permissions
  • Confirm GitLab accessibility
  • Recheck proxy settings
  • Retry connection test

​
Repositories Not Appearing

Possible Causes
  • Insufficient token permissions
  • Repository access restrictions
  • Synchronization delay
Resolution
  • Verify repository visibility
  • Confirm PAT scope permissions
  • Retry repository refresh

​
Integration Shows “Not Connected”

Possible Causes
  • Authentication failure
  • Expired token
  • Connectivity issues
Resolution
  • Reauthenticate the connection
  • Update the PAT token
  • Validate network access

​
Expected Outcome

After successful configuration:
  • GitLab repositories are connected to Engineering Metrics
  • Repository data becomes available for analytics
  • Projects can be mapped to repository scopes
  • Engineering metrics and repository insights begin synchronizing into the platform