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

​
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

​
Create a GitLab Personal Access Token

A GitLab Personal Access Token (PAT) is used to securely authenticate your GitLab account and allow the Engineering Metrics Dashboard to collect repository, project, pipeline, and work item metrics.

​
Prerequisites

Before creating a Personal Access Token, ensure that:
  • You have access to a GitLab account.
  • You have permission to create Personal Access Tokens.
  • You have access to the GitLab groups and projects that you want to integrate.

​
Steps to Create a Personal Access Token

​
Step 1: Sign in to GitLab

  1. Open GitLab and sign in using your account credentials.

​
Step 2: Open the Access Tokens Page

  1. Click your profile avatar in the upper-right corner.
  2. Select Edit profile.
  3. From the left navigation menu, select Access Tokens.
    • Depending on your GitLab version, this may appear as Personal Access Tokens.

​
Step 3: Configure the Token

Provide the required details.

​
Step 4: Configure Permissions

​
Required Token Scope

When creating your GitLab Personal Access Token, select one of the following scopes:
GitLab Personal Access Tokens support api and read_api scopes for G360. There are no separate permissions for projects, repositories, commits, pipelines, or work items to configure when creating the token.

​
Step 5: Create the Token

  1. Click Create personal access token.
  2. Copy the generated token immediately.
The Personal Access Token is displayed only once after it is created. Store it securely, as you will not be able to view it again.

​
Use the Token

To connect GitLab with the Engineering Metrics Dashboard:
  1. Navigate to Integrations.
  2. Select GitLab.
  3. Enter the generated Personal Access Token in the API Token field.
  4. Complete the remaining connection details.
  5. Save the connection.

​
Best Practices

  • Grant only the minimum permissions required.
  • Store the token securely using a password manager or secret management solution.
  • Rotate Personal Access Tokens periodically.
  • Revoke tokens that are no longer in use or have been compromised.
  • Avoid sharing Personal Access Tokens in source code, emails, or chat applications.

​
Minimum Required Permissions

When creating a GitLab Personal Access Token (PAT) for the Engineering Metrics Dashboard, configure the token with the following minimum permissions.

​
Minimum Required Permission Set

These are the minimum required permissions for the Engineering Metrics Dashboard to collect repository, project, pipeline, planning, and user-related metrics from GitLab. Granting additional permissions is not required unless your organization has specific integration requirements.
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
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:

​
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