Skip to main content

​
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

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

​
Creating A CircleCI Personal API Token

Follow the steps below to generate a Personal API Token.
  1. Sign in to your CircleCI account.
  2. Click your profile icon in the bottom-left corner.
  3. Select User Settings.
  4. Navigate to the Personal API Tokens section.
  5. Click Create New Token.
  6. Enter a descriptive name for the token. Example:
  7. Click Add API Token.
  8. CircleCI generates a new Personal API Token.
  9. Copy the token immediately and store it securely.
Warning: CircleCI displays the Personal API Token only once. If the token is lost, you must create a new token.

​
Minimum Required Access for G360 Integration

CircleCI Personal API Tokens do not support selecting individual scopes during token creation. The generated token inherits the permissions of the CircleCI user account that created it. To successfully connect CircleCI with G360, ensure that the user account creating the token has access to the following resources:
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
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 does not enforce a fixed default API request limit for G360 integrations. By default, API requests are not rate-limited unless a custom limit has been configured by your CircleCI administrator.
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
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