Add a Jira connector

Connect Harness to Jira as a Harness Jira connector.

Use a Harness Jira connector to connect Harness to Jira. This connector allows you to create and update Jira issues, and to use Jira issues in Approval steps.

Jira Software and Jira Service Management (JSM) are separate Atlassian products. Jira Software tracks software and project work such as issues, bugs, stories, epics, and sprints. JSM is built for IT service management, covering service requests, incidents, problems, changes, and customer support portals. To connect Harness to JSM, go to Add a JSM connector.

---

What you will learn from this topic

• The prerequisites for creating a Jira connector.

• Understand the limitations of the Jira connector.

• How to add a Jira connector using a username and API key, or a Personal Access Token.

• How to find YAML examples for each Jira connector authentication type.

---

Before you begin

• You can add a Jira connector at the Project, Organization, or Account scope.

• You need permission to create and edit connectors. For details, go to Configure RBAC.

• If Harness connects to Jira through a Harness Delegate, install and register a delegate before you configure the connector. For details, go to Delegate overview.

• The delegate you select for this connector must have network connectivity to the Jira API. If your Jira instance uses HTTPS with a certificate signed by a custom Certificate Authority (CA), add that CA certificate to the delegate.

• In Jira URL, use the base URL your users use to access Jira, for example https://your-domain.atlassian.net.

• For Jira Cloud, authenticate with a username (email address) and API token. For Jira Server or Data Center, authenticate with a username and password.

---

Limitations

Review the following limitations before you add a Jira connector.

• Your Jira REST API account must have permissions to create and edit issues in the relevant Jira projects. The Administer Jira permission includes all relevant permissions (as does the Administrator or Member permission on Jira next-gen). At minimum, your account requires the following Jira project permissions:

  • Browse projects

  • Create issues

  • Edit issues

  • Transition issues

  • Add comments, if Harness updates issue discussions For details, go to Atlassian's documentation on Operation Permissions, Issues, and Managing Project Permissions.

• When you set up the Jira connector, Username requires the full email address you use to log into Jira.

Add a Jira connector

You can add a Jira connector at the Project, Organization, or Account level. This topic covers the Project level. The process is the same for Organization and Account.

You can also add the Jira connector when setting up the Jira Create, Jira Approval, or Jira Update steps. This topic covers adding it to the Project's Connectors page.

To add a Jira connector to your Harness project:

Overview

Perform the following steps to name the connector:

1. In Project Setup, click Connectors.

2. Click New Connector, and then click Jira. The Jira connector settings appear.

3. In Name, enter a name for this connection. You will use this name to select this connection in Jira steps.

4. Click Continue.

Details

Perform the following steps to configure the Jira URL and authentication:

1. In Jira URL, enter the base URL by which your users access your Jira applications. For example: https://mycompany.atlassian.net.

   In Jira, the base URL is set to the same URL that Web browsers use to view your Jira instance. For details, go to Configuring the Base URL from Atlassian. If you are using on-premises Jira server with HTTPS redirects enabled, use the HTTPS URL to ensure the JIRA client follows redirects.

2. In Authentication, select one of the following:

   • Username and API Key: Enter your credentials in the Username and API Key fields.

     • In Username, enter the full email address you use to log into Jira.

     • In API Key, create or select a Harness secret that contains a scoped API token with the following scopes:

       • read:jira-user - Allows Harness to read user information.

       • read:jira-work - Allows Harness to read Jira issues and related data.

       • write:jira-work - Allows Harness to create and update Jira issues.

       • manage:jira-project - Allows Harness to read project-level settings and metadata during connection validation.

       • manage:jira-configuration - Allows Harness to read Jira configuration required for authentication and connection testing. To create a scoped API token, go to Manage API tokens for your Atlassian account from Atlassian. Once you create the scoped API token, add it as a Harness text secret. For a YAML example of this credential type, go to Connector YAML examples. To find your Cloud ID, go to Atlassian's guide on finding your Cloud ID.

   • Personal Access Token: In Personal Access Token, create or select a Harness secret that contains your Jira Personal Access Token (PAT). For a YAML example of this credential type, go to Connector YAML examples. To create a PAT, go to Using Personal Access Tokens from Atlassian.

3. Click Continue.

Personal Access Token authentication requires Harness Delegate version 78707 and later. Jira only supports Personal Access Tokens in its Server version. For the exact version, go to Using Personal Access Tokens.

Delegates Setup

Perform the following steps to select the Harness Delegates for this connector:

1. Select the Harness Delegates to use when making a connection to Jira using this connector.

2. Click Save and Continue.

Connection Test

Harness tests the connection.

Click Finish. The Jira connector is listed in Connectors.

Connector YAML examples

Use the following YAML examples to configure a Jira connector for each authentication type.

Username and API key

YAML example: Username and API key

connector:
  name: scopedJiraApiToken
  identifier: scopedJiraApiTokenID
  description: "scoped API token-based Harness connector for Jira"
  accountIdentifier: YOUR_ACCOUNT_IDENTIFIER
  orgIdentifier: YOUR_ORG_IDENTIFIER
  projectIdentifier: YOUR_PROJECT_IDENTIFIER
  type: Jira
  spec:
    jiraUrl: https://api.atlassian.com/ex/jira/{cloud_id} # Replace {cloud_id} with your actual Cloud ID from Jira
    auth:
      type: UsernamePassword
      spec:
        username: YOUR_EMAIL_ADDRESS_FOR_JIRA_LOGIN
        passwordRef: YOUR_TEXT_SECRET_CONTAINING_SCOPED_API_TOKEN
    ignoreTestConnection: false

Personal Access Token

YAML example: Personal Access Token

connector:
  name: jiraPat
  identifier: jiraPat
  description: ""
  orgIdentifier: default
  projectIdentifier: myproject
  type: Jira
  spec:
    jiraUrl: https://jira.dev.example.io/ # Replace with your Jira Server URL
    delegateSelectors:
      - YOUR_DELEGATE_SELECTOR
    auth:
      type: PersonalAccessToken
      spec:
        patRef: YOUR_TEXT_SECRET_CONTAINING_PAT

---

Next steps

• Create Jira issues in CD stages: Create Jira issues from a Continuous Delivery stage.

• Update Jira issues in CD stages: Update existing Jira issues from a Continuous Delivery stage.

• Adding Jira Approval Stages and Steps: Use Jira issues to gate pipeline approvals.