> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heygarth.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Gitlab

# 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

## Navigation

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**

```text theme={null}
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**

```text theme={null}
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**

```text theme={null}
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:

```text theme={null}
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