> For the complete documentation index, see [llms.txt](https://docs.cortex.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cortex.io/ingesting-data-into-cortex/integrations/harness/using-the-integration-for-harness.md).
# Using the integration for Harness
{% hint style="info" %}
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.
{% endhint %}
This article explains how to use the integration for Harness. For configuration instructions, see [Configuring Harness](/ingesting-data-into-cortex/integrations/harness.md).
After you configure Harness, you can trigger Harness pipelines directly from a Cortex Workflow using the **Execute pipeline** block. This replaces the custom webhook and raw HTTP approach, so you don't need to build and maintain a webhook trigger for every pipeline you want to run from Cortex.
## Prerequisites
1. A configured Harness integration.
2. The Harness API key used in that configuration must have permission to execute the pipelines you want to run.
3. Permission to create or edit Workflows in Cortex. See [Creating a Workflow](/streamline/workflows/create.md).
## Triggering a Harness pipeline from a Workflow
The **Execute pipeline** block runs a Harness pipeline as a step in a Workflow. You can chain it with other blocks, for example to require a manual approval before a deploy, or to post the run link to Slack after the pipeline starts.
**To add the Execute pipeline block to a Workflow**:
1. From the main sidebar, select **Workflows**.
2. Do one of the following:
* Select the **All** tab to search and filter across all of your organization's Workflows.
* Select the **Mine** tab to search and filter only the Workflows you own.
* Note that Cortex saves your selection and restores it the next time you open this page.
3. Locate the Workflow you want to edit, click the **overflow menu** next to it, then select **Edit workflow**.
4. Click the **+ icon**. The **Search for blocks** window opens.
5. Search for **Harness**, then select **Execute pipeline**.
6. In the side panel, configure the block metadata:
1. **Block name** - Optionally, change the name of the block. The name auto-populates based on the block name.
2. **Slug** - Optionally, change the slug. The slug auto-populates based on the block name and is made up of letters, digits, and hyphens.
3. **Alias** - From the dropdown, select the Harness configuration the block should use (required). See [Selecting the right configuration](#selecting-the-right-configuration) for more information.
4. Enter the required pipeline details:
1. Under **Organization identifier**, enter the identifier of the Harness organization that owns the pipeline (required).
2. Under **Project identifier**, enter the identifier of the Harness project that owns the pipeline (required).
3. Under **Pipeline identifier**, enter the identifier of the pipeline you want to run (required).
5. Optionally, add runtime inputs:
1. Under **Runtime inputs**, enter the pipeline's runtime input values as YAML. Use this to pass values the pipeline expects at execution time, such as an environment or an image tag.
2. Under **Notes**, enter a short description of the run. Cortex passes this to Harness so the execution is easier to identify in the Harness UI.
7. Click **Save**.
You can reference values from earlier blocks in any of these fields using Workflow state. See [Referencing Workflow state in a block](/streamline/workflows/blocks.md#referencing-a-workflow-state-in-a-block).
### Block outputs
When the pipeline is triggered successfully, the block returns:
* `execution_id` - The identifier of the Harness pipeline execution that was started.
* `status` - The execution status Harness reported at trigger time.
* `response` - The full response object from Harness, for any field not surfaced above.
Reference these in later blocks the same way you reference any other block output, for example to build a link to the execution or to branch on the returned status.
{% hint style="info" %}
The **Execute pipeline** block is synchronous. It returns as soon as Harness acknowledges the run, so `status` reflects the state of the execution at trigger, not the final result of the pipeline. To act on the pipeline's outcome, poll Harness in a later block or have the pipeline notify Cortex when it finishes.
{% endhint %}
### How the block authenticates
The block authenticates with the API key stored in the Harness configuration you select, so the pipeline runs as the owner of that key. It doesn't run as the person who started the Workflow. Keep this in mind when you set up Harness permissions and when you review pipeline audit logs, since every run started from Cortex is attributed to the key's owner.
### Selecting the right configuration
If you have more than one Harness configuration, always select an explicit **Configuration alias** on the block. A block left on the default configuration uses the default account's credentials, which is a common cause of unexpected `401` errors when you meant to use a different account.
This matters most for internally hosted instances. See [Using the block with Cortex Axon Relay](#using-the-block-with-cortex-axon-relay).
## Using the block with Cortex Axon Relay
The **Execute pipeline** block works with internally hosted Harness instances connected through [Cortex Axon Relay](/ingesting-data-into-cortex/integrations/harness.md#configuring-harness-with-cortex-axon-relay). The relay agent runs in your network and injects your Harness API key locally, so your credentials never leave your environment. For setup instructions, see Internally hosted integrations.
Two things to know when you use the block over the relay:
* **Select the relay-backed configuration alias on the block.** Cortex only routes a request through the relay when the block names a configuration alias. If the block is left on the default configuration, the request goes directly to Harness instead of through the relay and fails to authenticate.
* **Your Harness API key stays on-premises.** Cortex sends the request with a placeholder credential, and the relay agent replaces it with your real key before the request reaches Harness. Both personal access tokens and service account tokens are supported.
## Viewing Harness integration logs
{% hint style="info" %}
This feature is available in Cortex cloud.
{% endhint %}
While viewing an integration's settings page, select the **Logs** tab to view error logs from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).
Click into a row to get more information, including time stamp, status code, full error, and request path.
## Troubleshooting and FAQ
See frequently asked questions below.
The block returns a 401 or authentication error
Check the following:
* The block has an explicit **Configuration alias** selected. If it's set to the default configuration and your Harness instance is behind Cortex Axon Relay, the request bypasses the relay and fails.
* The API key in the selected configuration is still valid, and its owner has permission to execute the pipeline.
* The organization and project identifiers on the block match the account the selected configuration points at.
A relay-backed Harness configuration shows as failing validation
A newly created relay-backed configuration can show a failed connection test on the integration settings page, even when the setup is correct. Click **Test connection** on the configuration to re-run the check. If it still fails, confirm the Axon Relay agent is running and can reach your Harness host.
The pipeline started, but the Workflow moved on before it finished
This is expected. The **Execute pipeline** block returns as soon as Harness acknowledges the run. Use the returned `execution_id` in a later block to check the execution's final state in Harness.