> ## 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.

# Jenkins

***

# Jenkins CI/CD Integration

## Overview

The Jenkins CI/CD Integration allows Engineering Metrics to connect with Jenkins pipelines and collect CI/CD-related engineering data for analytics, deployment tracking, and DORA metrics reporting.

Using this integration, users can:

* Connect Jenkins environments
* Authenticate using Jenkins credentials
* Synchronize pipeline execution data
* Configure deployment stage tracking
* Enable CI/CD and DORA analytics within Engineering Metrics

The Jenkins integration follows a similar workflow to repository integrations such as GitLab and Bitbucket, with Jenkins-specific configuration for pipeline and deployment tracking.

## Navigation

To access Jenkins integrations:

1. Open the Engineering Metrics platform.
2. Navigate to **Integration → Data Integrations Hub**.
3. Under **CI/CD Integrations**, locate **Jenkins**.
4. Click:

   * **Connect** if no connection exists.
   * **Manage** if an existing connection already exists.

## Creating a New Jenkins Connection

Inside the Jenkins Connections page:

1. Click **New Connection**.
2. The Jenkins connection configuration modal opens.

## Connection Configuration Fields

### Connection Name

**Field:** Connection Name

**Purpose**

Defines a unique identifier for the Jenkins integration connection.

> Important: The connection name must be unique and should not duplicate existing connection names.

**Examples**

* Jenkins Production
* Jenkins CI Server
* Engineering Jenkins

### Endpoint URL

**Field:** Endpoint URL

**Purpose**

Defines the Jenkins server URL Engineering Metrics will connect to.

This may be:

* A locally hosted Jenkins instance
* A publicly deployed Jenkins environment

**Example**

```text theme={null}
https://jenkins.company.com/
```

> Important: The endpoint must be reachable from the Engineering Metrics environment.

### Username

**Field:** Username

**Purpose**

The Jenkins username used for authentication.

The account should have sufficient permissions to:

* Access Jenkins pipelines
* Read build and deployment information
* Retrieve pipeline execution data

### Password

**Field:** Password

**Purpose**

The authentication password or token associated with the Jenkins account.

> Important: Invalid credentials may cause:
>
> * Connection failures
> * Missing pipelines
> * Synchronization issues

### Proxy Configuration

**Field:** Proxy

**Purpose**

Allows Engineering Metrics to connect through a proxy server when required.

**Typical Use Cases**

* Enterprise firewalls
* Restricted network environments
* Internal infrastructure routing

**Example**

```text theme={null}
http://proxy.localhost:8080
```

> Note: This field is optional for most standard deployments.

### Custom Rate Limit

**Field:** Custom Rate Limit

**Purpose**

Allows manual configuration of API request frequency and synchronization throttling.

**Default Behavior**

Engineering Metrics automatically manages synchronization rates.

**When Enabled**

Users can configure custom limits to:

* Prevent excessive API calls
* Reduce Jenkins server load
* Optimize synchronization performance

## Testing the Connection

Before saving the connection:

1. Click **Test Connection**.

### Expected Result

Engineering Metrics validates:

* Jenkins server accessibility
* Username and password authentication
* Pipeline access permissions

If validation succeeds, the connection is ready to be saved.

## Saving the Connection

After successful validation:

1. Click **Save Connection**.

### Result

The Jenkins connection is added to the Connections panel.

## Managing Existing Connections

Users can:

* View configured Jenkins connections
* Search connections
* Select active connections
* Delete existing connections

### Delete Connection

A delete icon is available on the extreme right side of the connection entry.

**Purpose**

Allows users to remove existing Jenkins connections from Engineering Metrics.

> Important: Deleting a connection may stop synchronization for associated projects and pipelines.

## Data Scope Configuration

After creating the Jenkins connection:

1. Select the desired Jenkins connection.
2. Click **Add Data Scope**.

The Add Data Scope window opens.

### Pipeline Selection

The Data Scope page includes:

* Search bar for repository or pipeline lookup
* Pipeline and repository selection table

Displayed information includes:

* Repository Name
* Organization
* Last Updated Time

Users can:

* Search available Jenkins pipelines
* Select required pipelines
* Add them as synchronization scopes

### Adding a Data Scope

1. Search for the required pipeline or repository.
2. Select the desired entry.
3. Click **Add Scope**.

### Result

Selected Jenkins pipelines become available for synchronization and analytics.

## Scope Configuration

After adding a data scope, users can associate Scope Configurations with the selected scope.

Scope Configurations define:

* Which data entities are collected
* Pipeline deployment stage mappings
* CI/CD analytics configuration
* DORA metrics tracking behavior

### Common Data Entities

* CI/CD
* Deployment Data
* Pipeline Execution Data
* Cross Domain Metrics

## Deployment Stage Configuration

Inside Scope Configuration settings, users configure:

* Pipeline names
* Deployment stage identifiers

**Examples**

* deploy
* production
* release

**Purpose**

Allows Engineering Metrics to identify deployment-related activities required for:

* DORA metrics
* Deployment analytics
* Pipeline success tracking

> Important: Deployment stage naming depends on the Jenkins pipeline configuration used within the organization.

## Project Mapping

After configuring data scopes:

1. Navigate to the Projects section.
2. Create or edit a project.
3. Select the Jenkins connection.
4. Select the required pipeline scopes.
5. Configure synchronization behavior.
6. Complete setup.

## Sync Behavior Configuration

### Historical Data Collection

Users can define the historical duration for synchronization.

**Examples**

* Last 30 Days
* Last 6 Months
* Last 1 Year

### Sync Frequency

Defines how frequently synchronization occurs.

Available options include:

* Daily
* Weekly
* Monthly
* Custom Intervals

**Example**

```text theme={null}
Every 2 Hours
```

By default, synchronization runs automatically based on the configured schedule.

### Running Policy

**Option:** Skip Failed Task

**Purpose**

Allows synchronization jobs to continue even if individual subtasks fail.

**Benefit**

Prevents full synchronization failure caused by partial pipeline processing issues.

## DORA Metrics Configuration

To enable DORA metrics:

1. Navigate to project settings.
2. Enable deployment-related settings.
3. Save configuration changes.

> Important: DORA metrics configuration is specifically required for deployment analytics.

## Run Sync Now

**Button:** Run Sync Now

**Purpose**

Immediately synchronizes the latest Jenkins pipeline and deployment data.

**Behavior**

Only newly available data is collected during execution.

## Retransform Data

**Button:** Retransform Data

**Purpose**

Reprocesses previously synchronized data into standardized formats for reporting and analytics.

> Important: This process does not collect new data. It only transforms existing synchronized data.

## Status and Execution History

The Status section displays:

* Synchronization history
* Task execution duration
* Task completion status
* Success and failure states
* Execution timestamps

**Purpose**

Allows users to monitor synchronization behavior and troubleshoot issues.

## Best Practices

### Use Dedicated Jenkins Service Accounts

**Recommended**

Use a dedicated Jenkins integration account instead of personal user credentials.

**Benefits**

* Improved security
* Easier credential management
* Reduced operational dependency on individuals

### Use Stable Endpoint URLs

Ensure Jenkins endpoint URLs remain stable and accessible.

**Benefits**

* Prevents synchronization interruptions
* Reduces connectivity failures

### Configure Deployment Stages Properly

Ensure deployment stage names accurately reflect production deployment stages.

This is important for:

* DORA metrics accuracy
* Deployment analytics quality

### Limit Pipeline Scope

Only synchronize required pipelines.

**Benefits**

* Faster synchronization
* Reduced system load
* Improved dashboard performance

## Troubleshooting

### Test Connection Fails

**Possible Causes**

* Invalid credentials
* Incorrect endpoint URL
* Network accessibility issues
* Proxy misconfiguration

**Resolution**

* Verify Jenkins credentials
* Confirm endpoint accessibility
* Validate proxy settings
* Retry connection validation

### Pipelines Not Visible

**Possible Causes**

* Insufficient Jenkins permissions
* Pipeline access restrictions
* Synchronization delay

**Resolution**

* Verify account permissions
* Confirm pipeline visibility
* Retry synchronization

### Sync Failures

**Possible Causes**

* Pipeline processing failures
* Invalid deployment stage mappings
* API or server issues

**Resolution**

* Validate stage names
* Review synchronization logs
* Retry failed synchronization tasks

## Expected Outcome

After successful setup:

* Jenkins pipelines are connected to Engineering Metrics
* CI/CD pipeline data becomes available for analytics
* Deployment tracking is enabled
* DORA metrics can be generated
* Pipeline execution trends become visible within dashboards