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

# Circleci

***

# CircleCI CI/CD Integration

## Overview

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

Using this integration, users can:

* Connect CircleCI environments
* Authenticate using CircleCI API tokens
* Synchronize repository and pipeline activity
* Configure deployment tracking
* Enable engineering analytics and DORA metrics

The overall CircleCI workflow is similar to GitLab, Bitbucket, and Jenkins integrations, with CircleCI-specific authentication and endpoint configuration.

## Navigation

To configure CircleCI integration:

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

   * **Connect** for a new integration.
   * **Manage** for existing integrations.

## Creating a New CircleCI Connection

Inside the CircleCI Connections page:

1. Click **New Connection**.
2. The **Manage Connections: CircleCI** modal opens.

## Connection Configuration Fields

### Connection Name

**Field:** Connection Name

**Purpose**

Defines a unique name for the CircleCI integration connection.

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

**Examples**

* CircleCI Production
* CircleCI Engineering
* CircleCI Main Pipelines

### Endpoint URL

**Field:** Endpoint URL

**Purpose**

Defines the CircleCI API endpoint used for synchronization.

**Default Value**

```text theme={null}
https://circleci.com/api/v2
```

#### For CircleCI Cloud

The default endpoint is generally sufficient.

#### For Self-Hosted CircleCI Server

Users must provide their own deployed CircleCI server URL.

**Purpose**

Engineering Metrics uses this endpoint to:

* Fetch repository data
* Access pipeline information
* Retrieve build and deployment activity

### API Token

**Field:** API Token

**Purpose**

Used to authenticate the CircleCI integration.

The API token must have sufficient permissions to:

* Access repositories
* Read pipeline execution data
* Retrieve workflow information

The interface indicates that CircleCI Personal API Tokens can be created under:

**User Settings → Personal API Tokens**

> Important: Invalid or expired API tokens may cause:
>
> * Connection failures
> * Missing repositories
> * Synchronization issues

### Proxy Configuration

**Field:** Proxy

**Purpose**

Allows connections through enterprise proxy servers when direct CircleCI access is unavailable.

**Example**

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

**Typical Use Cases**

* Enterprise infrastructure
* Restricted corporate networks
* Internal routing requirements

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

### Custom Rate Limit

**Field:** Custom Rate Limit

**Purpose**

Allows manual control over synchronization request rates.

**Default Behavior**

Engineering Metrics automatically manages API request limits.

> CircleCI Note: The interface specifies that DevLake uses 10,000 requests/hour by default for CircleCI data collection.

**When Enabled**

Users can adjust synchronization speed to:

* Reduce API consumption
* Prevent throttling
* Optimize performance

## Testing the Connection

Before saving the connection:

1. Click **Test Connection**.

### Expected Validation

Engineering Metrics validates:

* API endpoint accessibility
* Token authentication
* Repository access permissions

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

## Saving the Connection

After successful validation:

1. Click **Save Connection**.

### Result

The CircleCI connection is added to the Connections panel.

## Managing Existing Connections

Users can:

* View existing CircleCI connections
* Search configured connections
* Select active integrations
* Delete connections

### Delete Connection

A **Delete Connection** button is available on the top-right section of the page.

**Purpose**

Removes the CircleCI integration from Engineering Metrics.

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

## Data Scope Configuration

After creating a connection:

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

The Add Data Scope modal opens.

### Repository Selection

The Data Scope interface includes:

* Repository search bar
* Repository selection table

**Displayed Columns**

* Repository Name
* Organization
* Last Updated

Users can:

* Search repositories
* Select repositories for synchronization
* Add repositories as active scopes

**Example Repositories**

* Word-game
* Dobble-game
* test-cc

### Adding a Data Scope

1. Select one or more repositories.
2. Click **Add Scopes**.

### Result

Selected repositories become available for:

* Pipeline synchronization
* Deployment analytics
* CI/CD reporting

## Scope Configuration

After adding scopes, users can associate Scope Configurations with the selected repository scopes.

Scope Configurations define:

* Which engineering entities are collected
* CI/CD synchronization behavior
* Deployment stage tracking
* DORA metrics configuration

The main CircleCI Connections page includes:

* Associate Scope Config
* Delete Data Scope
* Actions menu for each scope

## Project Mapping

After configuring scopes:

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

## Sync Behavior Configuration

CircleCI uses the same synchronization behavior flow described in other integrations.

### Historical Data Range

Users can define:

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

**Purpose**

Determines how much historical pipeline data is collected.

### Sync Frequency

Available scheduling options:

* Daily
* Weekly
* Monthly
* Custom Intervals

**Example**

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

**Purpose**

Controls how frequently Engineering Metrics synchronizes CircleCI data.

### Running Policy

**Option:** Skip Failed Task

**Purpose**

Allows synchronization jobs to continue even if individual subtasks fail.

**Benefit**

Prevents complete synchronization failures caused by isolated issues.

## DORA Metrics Configuration

For DORA metrics support, users must configure deployment-related pipeline stages during Scope Configuration.

**Examples**

* deploy
* release
* production

**Purpose**

Allows Engineering Metrics to identify deployment events required for:

* Deployment Frequency
* Change Failure Rate
* Lead Time
* Mean Time to Recovery (MTTR)

## Run Sync Now

**Button:** Run Sync Now

**Purpose**

Immediately synchronizes the latest CircleCI repository and pipeline data.

**Behavior**

Only newly available data is fetched during synchronization.

## Retransform Data

**Button:** Retransform Data

**Purpose**

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

> Important: This process does not collect new data. It only transforms previously collected data.

## Status and Execution History

The Status section displays:

* Synchronization history
* Execution timestamps
* Task completion details
* Runtime duration
* Success and failure information

**Purpose**

Allows monitoring and troubleshooting of synchronization activity.

## Best Practices

### Use Dedicated API Tokens

**Recommended**

Use organization-controlled CircleCI API tokens instead of personal user accounts.

**Benefits**

* Better security
* Easier maintenance
* Reduced dependency on individuals

### Limit Repository Scope

Only synchronize repositories required for reporting.

**Benefits**

* Faster synchronization
* Reduced API usage
* Improved dashboard performance

### Configure Deployment Stages Carefully

Ensure deployment stages accurately represent production deployments.

This is important for:

* Accurate DORA metrics
* Reliable deployment analytics

### Monitor API Usage

When using custom rate limits:

* Avoid excessive API requests
* Monitor synchronization performance
* Prevent CircleCI throttling

## Troubleshooting

### Test Connection Fails

**Possible Causes**

* Invalid API token
* Incorrect endpoint URL
* Network restrictions
* Proxy configuration issues

**Resolution**

* Verify token validity
* Confirm endpoint accessibility
* Validate proxy settings
* Retry connection validation

### Repositories Not Visible

**Possible Causes**

* Insufficient token permissions
* Repository access restrictions
* Synchronization delay

**Resolution**

* Verify API token permissions
* Confirm repository accessibility
* Retry synchronization

### Sync Failures

**Possible Causes**

* Pipeline processing issues
* Invalid deployment stage mappings
* API throttling

**Resolution**

* Review synchronization logs
* Adjust rate limits
* Validate stage configurations
* Retry failed synchronization tasks

## Expected Outcome

After successful setup:

* CircleCI repositories are connected to Engineering Metrics
* Pipeline and deployment data becomes available for analytics
* CI/CD trends can be monitored
* DORA metrics become available
* Synchronization occurs automatically based on configured schedules