> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/continuous-delivery/use-continuous-delivery/cd-building-blocks/cd-steps/builds/run-jenkins-jobs-in-cd-pipelines.md).

# Run Jenkins jobs in CD pipelines

Run a Jenkins job from a Continuous Delivery or custom stage and capture its output

{% hint style="info" %}
This feature is in Beta[^1] and requires enablement. [View all early access features.](https://developer.harness.io/release-notes/features.md)

{% @harness-feature-flag-access/request-feature-flag-access module="continuous-delivery" pagePath="continuous-delivery/use-continuous-delivery/cd-building-blocks/cd-steps/builds/run-jenkins-jobs-in-cd-pipelines" pageTitle="Run%20Jenkins%20jobs%20in%20CD%20pipelines" featureFlags="%5B%7B%22name%22%3A%22Multi-value%20Jenkins%20parameters%22%2C%22key%22%3A%22CDS\_JENKINS\_JSON\_PARAMS%22%2C%22status%22%3A%22BETA%22%2C%22description%22%3A%22Sends%20Jenkins%20Build%20step%20parameters%20through%20Jenkins'%20json%20form%20field%2C%20so%20a%20multi-select%20parameter%2C%20such%20as%20an%20Extended%20Choice%20checkbox%2C%20reaches%20the%20job%20with%20every%20value%20you%20select.%20Single-value%20String%2C%20Choice%2C%20and%20Boolean%20parameters%20are%20unaffected.%22%7D%5D" %}
{% endhint %}

Use the Jenkins step in a Continuous Delivery stage to run a Jenkins job and capture its inputs and outputs.

You can run Continuous Integration in Harness with the Continuous Integration module and [Continuous Integration pipelines](https://developer.harness.io/docs/continuous-integration/get-started/key-concepts/).

If you use Harness Continuous Delivery and not Harness Continuous Integration, you can still run Continuous Integration with the Jenkins step in a Continuous Delivery stage.

Harness integrates with [Jenkins](https://jenkins.io/) so you can run Jenkins jobs and capture inputs and outputs from the jobs.

***

## What you will learn from this topic

* How to [add the Jenkins step](#add-the-jenkins-step) to a Continuous Delivery or custom stage
* How to [select a job or folder](#jobfolder-name) and [set job parameters](#job-parameters)
* How to [pass multiple values to a Jenkins parameter](#pass-multiple-values-to-a-jenkins-parameter)
* How to [capture Jenkins environment variables](#captured-environment-variables-from-jenkins-builds) and [copy output expressions](#output-expressions)
* How to [select a branch on a multibranch pipeline](#multibranch-pipeline-support)

***

## Before you begin

Create the stage and the Jenkins connection the step uses:

* **Pipeline and stage**: Create a pipeline with a Continuous Delivery (deploy) or custom stage. The Jenkins step is available in those stage types only. Go to [Add a stage](https://developer.harness.io/docs/platform/pipelines/add-a-stage) to add a stage.
* **Jenkins connector**: Select a Jenkins server you already added as a Harness Jenkins connector. Go to [Connect to Jenkins](https://developer.harness.io/docs/platform/connectors/artifact-repositories/connect-to-jenkins/) to create the connector.

***

## Supported platforms and technologies <a href="#supported-platforms-and-technologies" id="supported-platforms-and-technologies"></a>

Go to [Supported platforms and technologies](https://developer.harness.io/continuous-delivery/new-to-continuous-delivery/cd-integrations.md) to review supported versions.

***

## Limitations and requirements <a href="#limitations-and-requirements" id="limitations-and-requirements"></a>

The Jenkins step has these limits:

{% hint style="warning" %}

* **EnvInject plugin**: For Harness to capture Jenkins environment variables, your Jenkins configuration requires the [EnvInject plugin](https://plugins.jenkins.io/envinject/). The plugin does not provide full compatibility with the pipeline plugin. Go to [known limitations](https://plugins.jenkins.io/envinject/#plugin-content-other-limitations) to review them.
* **Continuous Delivery and custom stages only**: The Jenkins step is available in Continuous Delivery (deploy) and custom stages only.
* **Jenkins with a GitHub plugin**: Branch names cannot contain double quotes if you use Jenkins with a GitHub plugin. If any previous build executed by Jenkins used a branch with double quotes in its name, delete the history of branches built already, or recreate the job.
* **Folder-level search**: With one-level folder listing enabled, the job picker search filters jobs and sub-folders at the current level only. It does not search the entire Jenkins job tree.
* **Runtime inputs for nested folders**: Runtime input and expressions are supported for the top-level **Job Name** field only. Settings for the folder levels you drill through after that support fixed values only.
* **No path validation until execution**: Harness does not validate a typed or selected job path against the Jenkins server before you run the pipeline. An incorrect path fails when the step executes.
  {% endhint %}

***

## Jenkins integration <a href="#jenkins-integration" id="jenkins-integration"></a>

With the **Jenkins** step, you can execute Jenkins jobs in the stage's shell session.

When you execute a job, you can also capture the output from the job at runtime, using runtime variables based on the context. You can then use those variables in another step in the same stage, in another stage, or in another pipeline.

### Information you can capture <a href="#what-information-is-available-to-capture" id="what-information-is-available-to-capture"></a>

Any Jenkins job information in the shell session of the pipeline can be captured and output using one or more Jenkins steps. You can also capture information available from the built-in Harness variables. Go to [Use Harness expressions](https://developer.harness.io/docs/platform/variables-and-expressions/harness-variables/) to reference built-in variables.

Capturing and exporting output in the Jenkins step can feed later steps. For example, a Jenkins step can capture Jenkins build information, a Harness service can echo that information and use it in a function, and the step can export the output down the pipeline for further evaluation.

***

## Add the Jenkins step <a href="#add-the-jenkins-step" id="add-the-jenkins-step"></a>

Perform the following steps to add the Jenkins step:

1. In the Continuous Delivery stage, select **Execution**.
2. Select **Add Step**.
3. Select **Jenkins**.

### Jenkins connector <a href="#jenkins-connector" id="jenkins-connector"></a>

Select the Jenkins server you added as a Harness Jenkins connector. Go to [Add a Jenkins connector](https://developer.harness.io/docs/platform/connectors/artifact-repositories/add-a-jenkins-connector) to create the connector.

### Polling frequency <a href="#polling-frequency" id="polling-frequency"></a>

Set the polling interval for verifying the progress of step execution. The interval must be less than the timeout configured for the step.

* **Default**: 5 sec
* **Minimum**: 5 sec

### Job or folder name <a href="#jobfolder-name" id="jobfolder-name"></a>

Select the Jenkins job (also called a project) to execute. The list is populated from the Jenkins server in the connector you selected.

{% hint style="info" %}
**Feature flag required**

One-level folder listing is behind the feature flag `CDS_JENKINS_ONE_LEVEL_JOB_LISTING`. Contact [Harness Support](mailto:support@harness.io) to enable the feature.
{% endhint %}

With this flag enabled, selecting a folder loads only the direct children of that folder, jobs and sub-folders, instead of loading every job in the subtree at once. For example, if you select the folder **apps**, Harness shows a new setting listing only the jobs and sub-folders directly inside **apps**. Select a sub-folder to load its direct children in another setting, and continue until you reach the job you want to run.

If you already know the full path to a job, you do not need to drill through each folder. Type the path directly into **Job Name**, for example `apps/team/deploy`.

To filter a job or folder, search for its name. Search matches jobs and sub-folders at the current level only; it does not search across the entire Jenkins job tree.

With the flag disabled, selecting a folder loads every job nested under it in a single flattened list. On Jenkins servers with large or deeply nested folder structures, this can take a long time to load and can make the job picker unresponsive.

### Runtime inputs and expressions <a href="#use-runtime-inputs-and-expressions" id="use-runtime-inputs-and-expressions"></a>

You can use runtime inputs or expressions for the Jenkins connector and job name.

Go to [Use Harness expressions](https://developer.harness.io/docs/platform/variables-and-expressions/harness-variables/) to reference runtime variables in your pipeline.

### Job parameters <a href="#job-parameters" id="job-parameters"></a>

If you use a [parameterized build](https://wiki.jenkins.io/display/JENKINS/Parameterized+Build), Harness populates the job parameters from the server when you select the job in **Job Name**.

![Job parameters populated from the Jenkins server](https://3694223630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fy1JhZ4oKIppwY7d5AhPj%2Fuploads%2Fgit-blob-a38aa8988fd5987dc76dd527015a51d0839b079e%2Fjenkinsparamfromjenkins.png?alt=media)

You can also add parameters manually. Select **Add Job Parameter**.

Runtime inputs and expressions are supported for the **Value** field only. You can reference a job parameter from the **Input** tab of the executed step.

The following table compares the parameters on the step with the inputs on the executed step:

| Job parameters from the Jenkins step                                                                                                                                                                                                                                   | Executed Jenkins step inputs                                                                                                                                                                                                                           |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ![Job parameters populated from the Jenkins server](https://3694223630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fy1JhZ4oKIppwY7d5AhPj%2Fuploads%2Fgit-blob-a38aa8988fd5987dc76dd527015a51d0839b079e%2Fjenkinsparamfromjenkins.png?alt=media) | ![Inputs on the executed Jenkins step](https://3694223630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fy1JhZ4oKIppwY7d5AhPj%2Fuploads%2Fgit-blob-528a94b6732fa7a44fecc02d822b351e6c98abd8%2Fxecutedjenkinsinputs.png?alt=media) |

### Pass multiple values to a Jenkins parameter <a href="#pass-multiple-values-to-a-jenkins-parameter" id="pass-multiple-values-to-a-jenkins-parameter"></a>

For a Jenkins parameter that accepts more than one selection, such as a checkbox-based Extended Choice Parameter, enter the selected values as a comma-separated list in the **Value** field, exactly as Jenkins expects them. For example, enter `INFRA_BUILD,DEPLOY_MANUALLY` to select both values. Harness sends this value to Jenkins unchanged, so the job receives every value you enter.

This delimiter handling requires the `CDS_JENKINS_JSON_PARAMS` feature flag. With the flag off, Harness uses the previous parameter submission method, and a job can receive an empty or malformed value for a multi-value parameter even though the step reports success.

{% hint style="info" %}
**Multi-level and cascading parameters are not supported**

Harness does not support Jenkins parameter types where the valid choices for one parameter depend on the value selected in another, such as Active Choices or Extended Choice Parameter's multi-level mode. Each row in the **Job Parameters** table is independent: Harness fetches parameter values once, when you select the job, and does not re-query Jenkins as you edit other rows.
{% endhint %}

Harness logs the names of the parameters sent to Jenkins in the step execution log. If Jenkins rejects the request because a parameter does not exist on the job or has an invalid value, correct the parameter in the step, or turn off the `CDS_JENKINS_JSON_PARAMS` feature flag for the account to return to the previous submission method.

### Treat unstable Jenkins status as success <a href="#treat-unstable-jenkins-status-as-success" id="treat-unstable-jenkins-status-as-success"></a>

When this setting is enabled, Harness treats `Unstable` statuses as `Success`.

### Advanced settings <a href="#advanced-settings" id="advanced-settings"></a>

In **Advanced**, you can use the following options:

* [Delegate selectors](https://developer.harness.io/docs/platform/delegates/manage-delegates/select-delegates-with-selectors/)
* [Conditional execution](https://developer.harness.io/docs/platform/pipelines/step-skip-condition-settings)
* [Failure strategy](https://developer.harness.io/docs/platform/pipelines/failure-handling/define-a-failure-strategy-on-stages-and-steps)
* [Looping strategy](https://developer.harness.io/docs/platform/pipelines/looping-strategies/looping-strategies-matrix-repeat-and-parallelism)
* [Policy enforcement](https://developer.harness.io/docs/platform/governance/policy-as-code/harness-governance-overview/)

***

## Captured environment variables from Jenkins builds <a href="#captured-environment-variables-from-jenkins-builds" id="captured-environment-variables-from-jenkins-builds"></a>

For Harness to capture Jenkins environment variables, your Jenkins configuration requires the [EnvInject plugin](https://plugins.jenkins.io/envinject/). The plugin does not provide full compatibility with the pipeline plugin. Go to [known incompatibilities](https://plugins.jenkins.io/envinject/#EnvInjectPlugin-Knownincompatibilities) to review them. Harness captures certain environment variables from the Jenkins build.

The following list shows examples of the environment variables and the expressions you can use to reference them:

* **Job status**: `<+execution.steps.[step_Id].build.executionStatus>`
* **Job URL**: `<+execution.steps.[step_Id].build.jobUrl>`
* **Build number**: `<+execution.steps.[step_Id].build.buildNumber>`
* **Build display name**: `<+execution.steps.[step_Id].build.buildDisplayName>`
* **Full build display name**: `<+execution.steps.[step_Id].build.buildFullDisplayName>`

The following sample script prints the captured values:

```bash
echo "Job Status:" <+execution.steps.Jenkins_Build.build.executionStatus>
echo "Job URL:" <+execution.steps.Jenkins_Build.build.jobUrl>
echo "Build number:" <+execution.steps.Jenkins_Build.build.buildNumber>
echo "Build display name:" <+execution.steps.Jenkins_Build.build.buildDisplayName>
echo "Full build display name:" <+execution.steps.[step_Id].build.buildFullDisplayName>
```

{% hint style="info" %}
If you use [step groups](https://developer.harness.io/continuous-delivery/use-continuous-delivery/cd-building-blocks/cd-steps/step-groups.md), the expressions must include the step group identifiers also.

For example, `<+execution.steps.[step group Id].steps.[step Id].build.jobUrl>`.
{% endhint %}

You can reference this job information in subsequent steps in your pipeline or in another pipeline.

To reference the job information in another stage in this pipeline, use the full pipeline path to the build information. For example, `<+pipeline.stages.[stage_Id].spec.execution.steps.[step_Id].build.executionStatus>`.

***

## Multibranch pipeline support <a href="#multibranch-pipeline-support" id="multibranch-pipeline-support"></a>

For Harness to capture Jenkins environment variables, your Jenkins configuration requires the [EnvInject plugin](https://plugins.jenkins.io/envinject/). The plugin does not provide full compatibility with the pipeline plugin. Go to [known incompatibilities](https://plugins.jenkins.io/envinject/#EnvInjectPlugin-Knownincompatibilities) to review them. The Jenkins multibranch pipeline (workflow multibranch) feature creates a Jenkins pipeline for each branch on your source control repository.

Each branch has its own [Jenkinsfile](https://jenkins.io/doc/book/pipeline/jenkinsfile/), which can be changed independently. This feature groups builds from feature or experimental branches.

In **Job Name**, multibranch pipelines are displayed alongside other jobs, with the child branches as subordinate options.

Perform the following steps to select a branch:

1. Select **>**.
2. Select the branch.

{% hint style="info" %}
Some components in Jenkins, such as controllers, might require a separate Harness Jenkins connector. The URL for accessing Jenkins can differ between Jenkins installations, or between instances of Jenkins running on the same server. If you have trouble integrating a Jenkins component, try a separate connector and update the connector URL.
{% endhint %}

***

## Output expressions <a href="#output-expressions" id="output-expressions"></a>

You can copy expressions for the job outputs from the **Output** tab of the Jenkins step.

![Output tab of the Jenkins step](https://3694223630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fy1JhZ4oKIppwY7d5AhPj%2Fuploads%2Fgit-blob-42b179679b8cd9395a0241006e613d3d8cdef94e%2Frun-jenkins-jobs-in-cd-pipelines-31.png?alt=media)

To access a Jenkins job environment variable from the step output, use:

`<+pipeline.stages.[STAGE_IDENTIFIER].spec.execution.steps.[STEP_IDENTIFIER].build.envVars.[ENV_VAR_FIELD]>`

When the step is inside a step group, use:

`<+pipeline.stages.[STAGE_IDENTIFIER].spec.execution.steps.[STEP_GROUP_IDENTIFIER].steps.[STEP_IDENTIFIER].build.envVars.[ENV_VAR_FIELD]>`

***

## Next steps

The following resources help you complete the setup and extend the Jenkins step in your pipeline:

* [Connect to Jenkins](https://developer.harness.io/docs/platform/connectors/artifact-repositories/connect-to-jenkins/): Create the Jenkins connector the step uses.
* [Use Harness expressions](https://developer.harness.io/docs/platform/variables-and-expressions/harness-variables/): Reference Jenkins output in a later step.
* [Step groups](https://developer.harness.io/continuous-delivery/use-continuous-delivery/cd-building-blocks/cd-steps/step-groups.md): Include the step group identifier when the Jenkins step is inside a step group.
* [Add a stage](https://developer.harness.io/docs/platform/pipelines/add-a-stage): Add the Continuous Delivery or custom stage that contains the Jenkins step.
* [Supported platforms and technologies](https://developer.harness.io/continuous-delivery/new-to-continuous-delivery/cd-integrations.md): Confirm the platforms Harness Continuous Delivery integrates with.

{% @harness-feedback/feedback %}

[^1]: Off by default. If you want to try it and share feedback, request access and Harness will turn it on for your account. Beta features can change and may not be ready for production use.
