Skip to main content

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