Skip to main content
Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor’s documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.
This article explains how to configure the integration for Harness. For instructions on importing Harness pipelines and deployments and mapping them to entities, see Importing data from Harness. For instructions on using the integration, including viewing pipelines and deployments and triggering Harness pipelines from a Workflow, see Using the integration for Harness.

Why use the integration for Harness

Harness is where your team builds and deploys software. Connecting it to Cortex ties your delivery pipelines to the services in your catalog, so your CI/CD platform and your system of record stay in sync. With the Harness integration, you can:
  • See where every service deploys. Cortex imports your Harness pipelines and deployments and shows them on each entity’s page, with status, version, environment, and a link to the run in Harness. Deployments also feed Eng Intelligence metrics.
  • Connect all of your Harness accounts. Cortex supports multiple configurations, so you can connect several Harness accounts and tie each one to entities using its own alias.
  • Keep internally hosted instances private. Use Cortex Axon Relay to connect a self-managed Harness instance without exposing it to the internet. The relay agent runs in your network and injects your API key locally, so credentials never leave your environment.
  • Verify your setup before you commit. Test a configuration directly from the settings page to confirm Cortex can reach your Harness account, whether you use a personal access token or a service account token.
  • Run pipelines from a Workflow. Use the Execute pipeline block to trigger a Harness pipeline as a step in a Cortex Workflow, without building a custom webhook trigger for each pipeline.

What Cortex imports from Harness

Cortex imports the following from each Harness configuration:
  • Organizations and projects
  • Services
  • Environments
  • Infrastructure definitions
  • Pipelines
  • Deployments, including failed deployments and rollbacks
Cortex doesn’t import deployment logs. To see a run’s logs, follow the link from Cortex to the run in Harness.

Configuring Harness

There are two options for integrating Harness: the default token configuration method and Cortex Axon Relay, a relay broker that allows you to securely connect your internally hosted Harness instance.

Prerequisites

  1. Users with the Configure Integrations permission can configure Harness.
  2. An API key in Harness. Cortex supports both personal access tokens and service account tokens. For instructions, refer to the Harness API key documentation.
  3. Your Harness account identifier. You can find this in Harness under Account settings, or in your Harness URL.

Configuring Harness with a token

  1. From the main sidebar, expand Integrations, then select Configurations.
  2. Locate Harness, then click Install. The Harness side panel opens.
  3. In the Harness side panel, click Token.
  4. Do the following:
    1. From the Category dropdown, select at least one category that applies to the integration (required).
    2. Under Configuration alias, enter the alias you’ll use to tie entity registrations to different configuration accounts (required).
    3. Under Account ID, enter your Harness account identifier (required).
    4. Under API key, enter your Harness API key (required). This can be a personal access token or a service account token.
    5. Under Host, enter the URL of your self-managed Harness instance. If you leave this field blank, Cortex defaults to https://app.harness.io.
  5. Click Test connection. A successful connection means your integration is configured correctly.
  6. Click Save.

Configuring Harness with Cortex Axon Relay

Use this option if your Harness instance is hosted in your own network and can’t be reached directly by Cortex.
  1. From the main sidebar, expand Integrations, then select Configurations.
  2. Locate Harness, then click Install. The Harness side panel opens.
  3. Click Relay.
  4. Do the following:
    1. From the Category dropdown, select at least one category that applies to the integration (required).
    2. Under Configuration alias, enter the alias you’ll use to tie entity registrations to different configuration accounts (required).
    3. Under Account ID, enter your Harness account identifier (required).
    4. Under Host, enter the URL of your self-managed Harness instance. If you leave this field blank, Cortex defaults to https://app.harness.io.
  5. Click Save.
  6. Set up the Axon Relay agent in your network. See Internally hosted integrations for instructions. For Harness, the relay agent routes requests to your Harness instance and injects your API key, so your credentials never leave your network.
On some self-managed Harness instances, the /ng API path is restricted. If the credential check fails with 403, include /gateway in the host URL (e.g., https://harness.example.com/gateway) so the full API path resolves to /gateway/ng/api/projects

Using multiple Harness configurations

The Harness integration supports multiple configurations. To add another:
  1. From the main sidebar, expand Integrations, then select Configurations.
  2. Locate Harness, then click Settings.
  3. In the upper-right corner of the page, click Add configuration.
  4. Follow the steps in either Configuring Harness with a token or Configuring Harness with Axon Relay.
Each configuration requires an alias, which ties entity registrations to a specific account. If no alias is specified, Cortex uses the default configuration. To set a default:
  1. From the main sidebar, expand Integrations, then select Configurations.
  2. Locate Harness, then click Settings.
  3. Click the pencil icon next to the configuration that should be the default.
  4. Toggle on Set as default. If you only have one configuration, it’s automatically set as the default.

How Cortex syncs Harness data

Harness limits external API requests to 400 calls per minute per API key. Cortex stays within this limit when it pulls data from Harness, so an ingestion cycle can take a while on large Harness accounts. For very large accounts, a single cycle can take several hours. Cortex doesn’t sync Harness on a fixed schedule. Instead, it starts a new ingestion cycle within 10 minutes of the previous cycle finishing. The time between updates depends on the size of your Harness account, and changes you make in Harness appear in Cortex after the next cycle completes. Cortex prioritizes your most active Harness projects so their deployments stay current. Each time Cortex checks a project and finds no new deployments, it waits longer before checking that project again. As soon as it finds a new deployment, it goes back to checking at the normal rate. This means a new deployment in a project that’s been inactive for a while can take longer to appear in Cortex than one in an active project. If ingestion takes too long for your account, you can ask Harness to raise your rate limit. If Harness increases it, contact the Cortex Customer Engineering team so Cortex can raise the limit it uses for your account. For details on Harness API limits, refer to the Harness platform rate limits documentation.
Last modified on November 9, 2026