Harness CI integration

Integrate Harness CI with OpenText Software Delivery Management, utilizing webhooks and secure credentials.

The integration enables you to receive and process webhooks events from Harness CI, providing enhanced visibility and traceability for your CI/CD workflows.

Supported features

The Harness CI integration provides the following functionality within OpenText Software Delivery Management.

Pipelines and builds

Collect pipeline step results
Run pipeline with parameters

Hierarchy in topology

Multi-branch pipeline
Collect failed build logs, configure automatic build failure classification
Trigger a CI job from a release process auto action

Hierarchy in topology

Multi-branch pipeline
Multiple spaces

Test automation

Collect test run results
Automatically set a test run's testing tool / test type
Run on-demand automated JUnit and NUnit tests
Run UFT One automated tests

Code coverage and Security

Collect code coverage reports

Prerequisites

Before starting the integration, verify the following prerequisites:

Harness Cloud
Administrator access on space and workspace
Administrator access to your Harness projects

Configuration parameters

Configure the following parameters to support the Harness integration.

Parameter	Default	Description
ENABLE_CI_INTEGRATION_FOR_HARNESS	false	Enables or disables Harness integration.

For details, see Configuration parameters.

Prepare Harness tokens

Use your Harness Admin user to create a new role with the following permissions:

Resource group	Permission
Organizations	View
Projects	View
Pipelines	View, Execute
Templates	View, Access
Webhooks	View

Create a service account and assign the previously created role.
To allow interaction with Harness, you need a token:
1. Go to your profile overview and add a new API key.
2. From the newly created API Key generate a token.

Set up credentials

Add the Harness token as credentials in OpenText Software Delivery Management.

To add credentials:

Open the global menu and select Administration > General Settings.
In the spaces sidebar, select a shared space or workspace.
Select the Credentials tab.
Click the + Credentials button.
Paste the Harness token into the password field.
In the Name and User Name fields, assign descriptive values that help identify the credential, such as the associated Harness user or purpose.

Add a Harness CI server

CI servers are defined at the workspace level.

To add a Harness CI server:

In the spaces sidebar, select a workspace.
Select the DevOps > CI Servers tab.
Click the + CI Server button.
Enter a name for the CI server and select Harness as the CI Server Type.
For the CI Server URL:
1. Open Harness CI and switch to Unified View.
2. Copy the URL prefix up to and including the organization ID.
3. Use the following example URLs:
  - Complete URL: https://app.harness.io/ng/account/{{account_id}}/all/orgs/{{organization_id}}/projects/{{project_id}}/overview
  - CI Server URL: https://app.harness.io/ng/account/{{account_id}}/all/orgs/{{organization_id}}
After the CI server is created successfully:
1. Add the Credential field to the CI server grid.
2. Assign the previously created credential.

Create API access tokens

Create API access tokens to use in the Harness webhooks.

To create API access tokens:

Select the shared space.
Select the API Access tab.
Click the + API access button.
Select Token as the type.
Assign the CI/CD Integration role for the relevant workspace.
Copy the generated token and store it securely. It is displayed only once. If lost, the token needs to be regenerated.

Configure Harness notifications (Webhook)

Configure a webhook notification in Harness to send pipeline and stage events to OpenText Software Delivery Management.

Create a notification template. Templates can be defined at the project, organization, or account level.
In the relevant project, organization, or account settings, create a new template with the following values:
- Template type: Notification
- Text type: JSON
- Name and Version: As required by your organization
Use the following JSON template content:

{
  "eventData": {
    "accountIdentifier": "<+account.identifier>",
    "accountName": "<+account.name>",
    "orgIdentifier": "<+org.identifier>",
    "orgName": "<+org.name>",
    "projectIdentifier": "<+project.identifier>",
    "projectName": "<+project.name>",

    "planExecutionId": "<+pipeline.executionId>",
    "executionUrl": "<+pipeline.executionUrl>",
    "pipelineUrl": "{{HOST_URL}}/ng/#/account/<+account.identifier>/ci/orgs/<+org.identifier>/projects/<+project.identifier>/pipelines/<+pipeline.identifier>/pipeline-studio",
    "eventType": "<+notification.eventType>",

    "pipelineIdentifier": "<+pipeline.identifier>",
    "pipelineName": "<+pipeline.name>",
    "pipelineStatus": "<+pipeline.status>",
    "pipelineStartTs": "<+pipeline.startTs>",
    "pipelineEndTs": "<+pipeline.endTs>",

    "stageIdentifier": "<+stage.identifier>",
    "stageName": "<+stage.name>",
    "stageStatus": "<+stage.status>",
    "stageStartTs": "<+stage.startTs>",
    "stageEndTs": "<+stage.endTs>",

    "runSequence": "<+pipeline.sequenceId>",
    "branch": "<+pipeline.branch>",

    "triggeredBy": {
      "triggerType": "<+pipeline.triggerType>",
      "name": "<+pipeline.triggeredBy.name>",
      "email": "<+pipeline.triggeredBy.email>"
    }
  }
}

Set {{HOST_URL}} to the base Harness URL (protocol and host only).
- Complete URL: https://app.harness.io/ng/account/{{account_id}}/all/orgs/{{organization_id}}/projects/{{project_id}}/overview
- HOST_URL: https://app.harness.io
Open the target pipeline in Harness, go to Pipeline Studio, and select Notify in the right pane.
Add a new notification rule and provide a name.
Set the event scope:
- Pipeline events: Pipeline Start, Pipeline End, Stage Start, Stage Success, Stage Failed
- Stage events: All

Select Webhook as the notification method, and configure the following settings:

Setting	Definition
URL	{{SDP_url}}/api/shared_spaces/{{space_id}}/analytics/ci/harness_ci/webhook-events SDP_url: The base URL of OpenText Software Delivery Management. space_id: The ID of the shared space where the CI Server was added.
Custom headers	Add the following custom headers: ALM-OCTANE-TECH-PREVIEW: true Authorization: Bearer {{SDP_token}} SDP_token is the API access token generated by OpenText Software Delivery Management.

Setting

Definition

URL

{{SDP_url}}/api/shared_spaces/{{space_id}}/analytics/ci/harness_ci/webhook-events

SDP_url: The base URL of OpenText Software Delivery Management.
space_id: The ID of the shared space where the CI Server was added.

Custom headers

Add the following custom headers:

ALM-OCTANE-TECH-PREVIEW: true
Authorization: Bearer {{SDP_token}}

SDP_token is the API access token generated by OpenText Software Delivery Management.

Important: Notification settings are stored in the pipeline YAML as plain text. To protect sensitive values, store {{SDP_token}} as a secret and reference it from the header value.

Example: Bearer <+secrets.getValue("SDP_token")>

For Notification template, select the template you created earlier.
Select the appropriate connectivity mode for your infrastructure.

Work with pipelines

Use the following procedures to work with Harness pipelines in OpenText Software Delivery Management.

Add a Harness pipeline

Open the global menu and select Quality Management > Pipelines > Management.
Click the + Pipeline button.
Select the Harness CI server you configured, then choose the relevant project and job from Harness pipelines.

Depending on your pipeline selection, a standard or a multi-branch pipeline is created in OpenText Software Delivery Management, which serves as a reference to the corresponding Harness pipeline.

Note: The pipeline must be executed at least once in Harness for it to appear in OpenText Software Delivery Management.

Manage inline pipelines

Inline pipelines are pipelines whose configuration files (YAML) are stored directly within Harness CI rather than in a Git repository. As a result, these pipelines are not associated with a source control branch. For such pipelines, a standard pipeline will be created in OpenText Software Delivery Management, without any branch-specific mapping.

Manage multi-branch pipelines

Multi-branch pipelines automatically track runs from any branch in your Harness project. Users can configure branch filters to control which branches are monitored and injected into OpenText Software Delivery Management.

Inject test results and collect code coverage

To inject automated tests and code coverage reports, Octane Collection tool is used to push XML test results and coverage reports from the Harness pipelines to OpenText Software Delivery Management. For usages and configuration of Octane Collection tool, see documentation.

Usages and examples for Octane collection tool:

A typical CLI invocation with coverage reports and test results:

java -jar octane-collection-tool.jar /
--server {{SDP_SERVER_URL}} /
--shared-space {{SHARED_SPACE_ID}} /
--workspace {{WORKSPACE_ID}} /
--bearer-token "{{SDD_TOKEN}}" /
--build-context-server-id "{{SDD_CI_SERVER_INSTANCE_ID}}" /
--build-context-build-id "stage|~~|<+org.identifier>|~~|<+project.identifier>|~~|<+pipeline.identifier>|~~|<+stage.identifier>" /
--build-context-job-id "<+stage.identifier>~<+pipeline.executionId>~<+pipeline.sequenceId>" /
--coverage-reports "path_to_coverage_reports/sample-jacoco.xml" /
--coverage-report-type "JACOCOXML" /
--field "Framework:JUnit" /
--field "Testing_Tool_Type:Selenium" /
--field "Test_Level:Integration Test" /
"{{PATTERN/PATH_TO_UNIT_TESTS}}"

A typical CLI invocation with coverage reports only:

java -jar octane-collection-tool.jar /
--server {{SDP_SERVER_URL}} /
--shared-space {{SHARED_SPACE_ID}} /
--workspace {{WORKSPACE_ID}} /
--bearer-token "{{SDD_TOKEN}}" /
--build-context-server-id "{{SDD_CI_SERVER_INSTANCE_ID}}" /
--build-context-build-id "stage|~~|<+org.identifier>|~~|<+project.identifier>|~~|<+pipeline.identifier>|~~|<+stage.identifier>" /
--build-context-job-id "<+stage.identifier>~<+pipeline.executionId>~<+pipeline.sequenceId>" /
--coverage-reports "path_to_coverage_reports/sample-jacoco.xml" /
--coverage-report-type "JACOCOXML"

A typical CLI invocation with test results only:

java -jar octane-collection-tool.jar /
--server {{SDP_SERVER_URL}} /
--shared-space {{SHARED_SPACE_ID}} /
--workspace {{WORKSPACE_ID}} /
--bearer-token "{{SDD_TOKEN}}" /
--build-context-server-id "{{SDD_CI_SERVER_INSTANCE_ID}}" /
--build-context-build-id "stage|~~|<+org.identifier>|~~|<+project.identifier>|~~|<+pipeline.identifier>|~~|<+stage.identifier>" /
--build-context-job-id "<+stage.identifier>~<+pipeline.executionId>~<+pipeline.sequenceId>" /
--field "Framework:JUnit" /
--field "Testing_Tool_Type:Selenium" /
--field "Test_Level:Integration Test" /
"{{PATTERN/PATH_TO_UNIT_TESTS}}"

Run pipelines

You can run standard pipelines or single-branch pipelines directly from OpenText Software Delivery Management. Multi-branch pipelines can only be run from Harness.

Pipeline configuration	Run details
Pipelines without variables	Run directly from OpenText Software Delivery Management without any additional configuration.
Pipelines with variables	The runtime variables defined in Harness pipelines are used. To fetch current variables values from Harness, select Sync with CI.

Trigger pipeline run from Auto Action

You can also run pipelines from Auto Action (Run job action). The pipelines eligible for this functionality are the ones which had defined the following variable as runtime input at the pipeline level in Harness CI: octane_auto_action_execution_id. For more details, see Auto actions.

Run tests

Test runners in OpenText Software Delivery Management enable users to execute automated tests through dedicated Harness pipelines.

The corresponding pipeline for the test runner needs to be added to OpenText Software Delivery Management prior to running automated tests.

Define the following variables as runtime inputs at the pipeline level in Harness CI: testsToRun, suiteId, suiteRunId and executionId. The variables don't need to have a specific value they can be let as empty values (<+input>).

To execute specific tests, use the testsToRun variable in the command that runs the tests.

Example (Maven): mvn test -Dtest="<+pipeline.variables.testsToRun>"

When creating a test runner in OpenText Software Delivery Management, select the appropriate testing framework. Supported frameworks for Harness CI: JUnit, NUnit or UFT. The testsToRun parameter is generated automatically based on the selected tests from OpenText Software Delivery Management.