Jira Integration

Updated 1 week ago by Michael Cretzman

Atlassian Jira provides dev teams with project management and issue tracking throughout the software delivery lifecycle. Harness integrates with Jira to enable you to track the progress of deployments by creating and updating Jira issues from Harness, and approve deployment stages using Jira issues as part of Workflow and Pipeline approvals.

For example, you could create a Jira issue when your deployment Pipeline execution starts, and update the same Jira ticket when each Workflow in the Pipeline complete successfully. And you can use the Jira issue status to approve or reject a deployment.

Add Jira as a Collaboration Provider

To use Jira integration in your Workflow or Pipeline, you need to add a Jira account as a Harness Collaboration Provider.

For steps on adding Jira as a Collaboration Provider, see Jira. Once you have added a Jira account to Harness, you can integrate Jira into your Workflows and Pipelines.

Create a Jira Issue Using a Workflow

You can create a Jira issue as a step in the execution of a Workflow. You can add a Jira step to any of the Workflow deployment steps (for example, Setup Container, Deploy Containers, Verify Service, and Wrap Up) and Rollback Steps.

When you add a step to a Workflow creating a Jira issue, the Workflow will create a new, independent Jira issue every time it is run.

To create a Jira issue as part of a Workflow, do the following:

  1. Ensure you have added a Jira account as a Harness Collaboration Provider, as described in Jira.
  2. Create a new or open an existing Harness Workflow.
  3. In any of the deployment or rollback steps, click Add Command. The Add Command dialog appears.

  4. In Collaboration, click Jira. The Jira dialog appears.

The Jira dialog has the following fields:

  • Title - By default, the step is titled Jira. If you are creating a Jira issue, you might want to rename the step Jira Creation, for example.
  • Request Type - Select Create an Issue. Update an issue is discussed in Update an Issue in a Workflow.
  • Jira Connector - Select the Jira account to use by selecting the Jira Collaboration Provider set up for that account. For more information, see Jira.
  • Project - Select a Jira project from the list. A Jira project is used to the create the issue key and ID when the issue is created. The unique issue number is created automatically by Jira.
  • Issue Type - Select a Jira issue type from the list issues types in the Jira project you selected.
  • Priority - Select a priority for the Jira issue. The list is generated from the Jira project you selected.
  • Labels - Add labels to the issue. These will be added to the Jira project you selected.
  • Summary - Required. Add a summary for the Jira issue you are creating. This is commonly called an issue title.
  • Description - Add the issue description.
  • Output in the Context - Click this option to create and pass variables from this Jira issue to another step in this Workflow or to a Pipeline step. For more information, see Jira Issue Variables.

When the Jira dialog is complete, it will look something like this:

Note the use of Harness variables in the Summary and Description fields:

Deployment url : ${deploymentUrl}
Artifact: ${artifact.displayName}
Build number: ${artifact.buildNo}

The variables will be replaced at runtime with deployment information. For more information on Harness variables, see Variables and Expressions in Harness. You can see this below.

When the Workflow is deployed, in the Harness Manager Deployments page, you can see a link to the Jira issue created by the Jira step:

Click the link to see the Jira issue created:

Note how the Harness variables were replaced with values. Try it yourself.

Jira Issue Variables

When you add a Jira step to a Workflow to create a Jira issue, you can create an output variable that can be used to reference that Jira issue in other Workflow steps or Pipelines that use that Workflow.

Using Jira issue variables involves three steps:

  1. Identify a new or existing Jira issue using a Jira step in a Workflow.
  2. Create an output variable in the step for the Jira issue.
  3. Reference the Jira issue in a Workflow, Phase, or Pipeline using the output variable and a Jira issue property, such as an issue ID.

For example, to reference a Jira issue, in the Jira step in a Workflow, you create an output variable, such as Jiravar.

The output variable identifies the Jira issue you created. When you reference the Jira issue in another Workflow, Phase, or Pipeline step, you use the issueId property. For example, ${Jiravar.issueId}.

Presently, the only Jira issue element you can reference is the Jira issue Key or ID using issueId. Harness will be adding more Jira issue element variables in the near future.

To create a Jira issue variable, do the following:

  1. In a Workflow, in any of the deployment or rollback steps, click Add Command. The Add Command dialog appears.
  2. In Collaboration, click Jira. The Jira dialog appears.
  3. Click Create an Issue and fill out the Jira dialog. In this example, we create a new Jira issue, but you can also create an output variable if the Update an Issue settings are used.
  4. Click Output in the Context. The Variable Name and Scope settings appear.

  5. In Variable Name, enter a name for your variable, such as Jiravar.
  6. In Scope, select Pipeline, Workflow, or Phase.

    The Pipeline scope is the widest, and includes the Workflow and Phase scopes. Next widest is Workflow, and includes any phases within that Workflow. And finally, Phase scopes the variable to the Workflow phase in which is was created.

    For example, a variable with a Pipeline scope can be used by any step in the Pipeline which uses this Workflow, such as an Approval Step. For this example, we will use the Pipeline scope.
  7. Click SUBMIT. The variable is created.

Next, let's reference the variable, named Jiravar, in another Workflow step, and then a Pipeline step.

  1. In the same Workflow, in any of the deployment or rollback steps, click Add Command. The Add Command dialog appears.
  2. In Collaboration, click Jira. The Jira dialog appears. We will update the Jira issue in this step, so you might want to rename the step title to Jira Update.
  3. Click Update an Issue. The settings for updating a Jira issue appear.

  4. Select the same Jira Connector and Project that you used when you added the Jira step to create the issue.
  5. In Key (Issue ID), enter the variable that references the Key or ID of the issue you created. You reference the Key/ID using the property issueId. In our example, we created a variable named Jiravar, and so the variable reference is ${Jiravar.issueId}.
  6. Next, enter text to update the Jira issue referenced by ${Jiravar.issueId} using the Update Summary and Update Status fields.

Next, let's use the ${Jiravar.issueId} variable in a Pipeline. For information on creating Pipelines, see Pipelines.

  1. Create or use an existing Pipeline.
  2. Add the Workflow using ${Jiravar.issueId} variable to the Pipeline.
  3. Click the + button to insert a stage into the Pipeline.



    The new stage dialog appears.
  4. Click Approval Step. The dialog changes to display the approval settings.
  5. In Ticketing System, select Jira Service Desk. The Jira settings appear.

  6. Select the Jira Connector and Project that you used when creating and updating the issue.
  7. In Key (Issue ID), enter the Jira issue variable you created, ${Jiravar.issueId}.

  8. Fill out the rest of the Approval Step as described in Jira-based Approvals.
  9. Click SUBMIT.

Update a Jira Issue using a Workflow

You can update an existing Jira issue in two ways:

  • Simply copy the Jira issue Key/ID from Jira and paste it into the Key (Issue ID) field in the Update an Issue settings of the Jira step in the Workflow.

  • Use the issueId variable property to update a Jira issue you created with Harness, for example ${Jiravar.issueId}:

To update a Jira issue in a Workflow using the issueId variable property, do the following:

  1. Create a new Jira issue using the Jira step in a Workflow, as described in Create an Issue in a Workflow.
  2. In the Jira step, click Output in the Context. The Variable Name and Scope settings appear.
  3. In Variable Name, enter a name for your variable, such as Jiravar.
  4. In Scope, select Pipeline, Workflow, or Phase.
  5. Click SUBMIT to complete the Jira step.
  6. Within the scope you set (this includes another Workflow in a Pipeline), click Add Command. The Add Command dialog appears.
  7. In Collaboration, click Jira. The Jira dialog appears. We will update the Jira issue in this step, so you might want to rename the step title to Jira Update.
  8. Click Update an Issue. The settings for updating a Jira issue appear.
  9. Select the same Jira Connector and Project that you used when you added the Jira step to create the issue.
  10. In Key (Issue ID), enter the variable that references the Key/ID of the issue you created. You reference the Key/ID using the property issueId. In our example, when you created an output variable in the Jira step that created the Jira issue, the variable was named Jiravar, and so the variable reference is ${Jiravar.issueId}.
    Now this Jira step will update the same Jira issue.
  11. Next, enter text to update the Jira issue referenced by ${Jiravar.issueId} using the Update Summary and Update Status fields.

Here's an example where the Jira step is used to create a new Jira issue and uses the output variable Jiravar. The variable is scoped to Pipeline in order for another Workflow to update the Jira issue.

Here's the Jira step to create the Jira issue:

Here's the new Jira issue in Jira:

Here's the Jira step to update the Jira issue, note the comment in Add Comment, Prov Workflow Complete:

During deployment, the Harness Manager Deployments page contains a link to the updated Jira issue:

Here's the updated Jira issue in Jira, note the Comment Prov Workflow Complete:

Jira-based Approvals

You can add approval steps in both Workflows and Pipelines, and use Jira issue workflow statuses for approval and rejection criteria.

Here is an example of the workflow statuses for a Jira issue:

Here is a Workflow Jira approval step using the same Jira statuses for criteria:

You can add a Jira approval step in a Workflow or Pipeline, but for this example we will use a Pipeline. The Jira approval settings are the same in the Jira approval step in a Workflow or Pipeline.

Here is a Pipeline containing two Workflows and a Jira Approval step.

The first Workflow includes a Jira step that creates a new Jira issue, as described in Create a Jira Issue Using a Workflow:

The Variable Name is Jiravar and the Scope is Pipeline. This will enable the output variable to be used in any stage of the Pipeline. The output variable uses the issueId property and so the resulting variable reference is ${Jiravar.issueId}. You can reference the Jira issue anywhere in the Pipeline using ${Jiravar.issueId}.

Next, let's add a Pipeline Approval step that uses ${Jiravar.issueId}.

In a Pipeline, click the Insert a Stage (+) button to add the Approval step:

The new stage dialog appears. Click Approval Step to see the approval settings.

The Approval Step has the following fields:

  • Ticketing System - For Jira, select Jira Service Desk.
  • Jira Connector - Select the Jira account you want to use by selecting the Collaboration Provider you added for the account, as described in Add Jira as a Collaboration Provider.
  • Project - Select the Jira project containing the Jira issue you will use for approval.
  • Key/Issue ID - Enter the output variable for a Jira issue created in a Workflow, such as ${Jiravar.issueId}. Although we are demonstrating approval using the ${Jiravar.issueId} variable, you can also simply enter the Jira Key/Issue ID for any Jira issue in the Jira project.
  • Timeout - Enter how long Harness should wait for the approval or rejection before failing the deployment.
  • Approved Status Criteria - The Field Name, Operator, and Value drop-down menus are populated from the Jira project you selected. Define the approval criteria using the Jira status items.
  • Rejected Status Criteria - Define the rejection criteria using the Jira status items.

When you finished, the approval step will look something like this:

When you deploy the Pipeline, the Approval Stage will display a link to the Jira issue selected for the approval:

Click the link in the Approval step to see the Jira issue in Jira.

Select the Approval criteria. In this example, the status Approved is the approval criteria.

Once the Jira issue is approved, the Approval stage is green in Deployments, and the deployment continues:


How did we do?