Jira Integration

Updated 1 month 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 that creates a Jira issue (as opposed to updating an 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 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 of 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.
  • Configure Fields - You can enable this control to target specific fields within a Jira issue. For more information, see Jira Custom Fields.

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 general information on Harness variables, see Variables and Expressions in Harness. For specifics, see Jira Issue Variables 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 that's been 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 it 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.

Jira Custom Fields

Once you've filled in the Jira dialog's required Jira Connector, Project, and Issue Type fields, the dialog's Configure Fields control is enabled. Open this pop-up to select specific fields within the Jira issue you're creating or updating.

As you select fields, they appear below the pop-up. You can then configure these fields with the values you want to apply to the Jira issue you're targeting.

Certain Jira fields—including Assignee, Sprint, and Time Spent—are not accessible in Harness' Jira integration.

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, Prod 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. For more information, see Jira-based Approvals.


How did we do?