Skip to main content

CircleCI

CatalogScorecards

CircleCI is continuous integration and continuous delivery platform that can be used to implement DevOps best practices. By integrating CircleCI with Cortex, you can conveniently access information about your workflows & pipelines.

In this guide, you'll learn how to set up and use the CircleCI integration to drive insights into your CI/CD infrastructure.

Setup and configuration​

Getting started​

In order to connect Cortex to your CircleCI instance, you’ll need to create a CircleCI API token.

Configuration​

Once you’ve created a CircleCI API token, you can configure the integration in Cortex from the CircleCI page in settings.

caution

If you do not see the settings page you're looking for, you likely don't have the proper permissions and need to contact your admin.

From the CircleCI settings page, you’ll see the option to Add CircleCI configuration.

  • Account alias: Used to tie entity registrations to different configuration accounts
  • API token: Personal access token generated earlier
  • Host: URL for your CircleCI instance if self-hosted, e.g. https://cortex.circleci.com

Once you save your configuration, you'll see the last four characters of the token you entered. If you’ve set everything up correctly, you’ll see the option to Remove Integration in Settings.

You can also use the Test all configurations button to confirm that the configuration was successful. If your configuration is valid, you’ll see a banner that says “Configuration is valid. If you see issues, please see documentation or reach out to Cortex support.”

The CircleCI integration has multi-account support so you can add a configuration for each additional by repeating the above process.

Each configuration requires an alias, which Cortex uses to correlate the designated with registrations for various entities. Registrations can also use a default configuration without a listed alias.

You can edit aliases and default configurations from the CircleCI page in settings. Select the edit icon next to a given configuration and toggle "Set as default" on. If you only have one configuration, it will automatically be set as the default.

Self-hosted CircleCI instances​

If you’re using a self-hosted instance of CircleCI, you’ll need to verify that your Cortex instance is able to reach the CircleCI instance.

caution

If you're using a self-hosted instance of CircleCI, you'll need to verify that your Cortex instance is able to reach the CircleCI instance.

We route our requests through a static IP address. Reach out to support at help@cortex.io to receive details about our static IP. If you're unable to directly allowlist our static IP, you can route requests through a secondary proxy in your network that has this IP allowlisted and have that proxy route traffic to your CircleCI instance.

If you're unable to directly allowlist our static IP, you can route requests through a secondary proxy in your network that has this IP allowlisted and have that proxy route traffic to your CircleCI instance.

Registration​

Entity descriptor​

You can set up the CircleCI integration for an entity by specifying its project slug in the x-cortex-circle-ci section of the entity descriptor.

x-cortex-circle-ci:
  projects:
    - projectSlug: circleci-projectslug # projectslug in CircleCI
      alias: circleci-alias # alias is optional and only relevant if you have opted into multi account support

Expected results​

Entity pages​

With the CircleCI integration, you can find metric & pipeline details on an entity's details page as long as that entity is associated with a project from your CircleCI instance.

From the Integrations tab in the sidebar, you can open the CircleCI page to find the metric & pipeline details for that entity.

Scorecards and CQL​

Once the CircleCI integration is established, you can create Scorecard rules and write CQL queries based on CircleCI metrics & pipelines:

  • Rate of success for pipelines
  • Number of flaky tests in a pipeline
  • Average runtime for a workflow
  • Success rates for projects
  • Project settings including PR branch overrides & other environment variables

Real-world examples​

For a Scorecard focused on development maturity, you can set a rule to make sure projects have:

  • a success rate over 90%:
circleci.projects().all((project) => project.metrics.successRate > 0.9) == true
  • no flaky tests:
circleci.flakyTests().length == 0

Still need help?​

The following are all the ways to get assistance from our customer engineering team. Please use the option that is best for your users:

  • Email: help@cortex.io, or open a support ticket in the in app Resource Center
  • Chat: Available in the Resource Center
  • Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your customer success manager.