> 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/harness-platform/use-harness-platform/connectors/ticketing-systems/connect-to-jira.md).
# 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](/harness-platform/new-to-harness-platform/overview.md#connectors) 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](/harness-platform/use-harness-platform/connectors/ticketing-systems/connect-to-jsm.md).
***
## What you will learn from this topic
* The [prerequisites](#before-you-begin) for creating a Jira connector.
* Understand the [limitations](#limitations) of the Jira connector.
* How to [add a Jira connector](#add-a-jira-connector) using a username and API key, or a Personal Access Token.
* How to find [YAML examples](#connector-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](/harness-platform/use-harness-platform/platform-access-control/configure-rbac.md).
* 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](/harness-platform/use-harness-platform/delegates/delegate/delegate-concepts/delegate-overview.md).
* 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](https://confluence.atlassian.com/jirasoftwarecloud/overview-of-permissions-in-next-gen-projects-959283605.html)). 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](https://developer.atlassian.com/cloud/jira/platform/rest/v3/?utm_source=%2Fcloud%2Fjira%2Fplatform%2Frest%2F\&utm_medium=302#permissions), [Issues](https://developer.atlassian.com/cloud/jira/platform/rest/v3/?utm_source=%2Fcloud%2Fjira%2Fplatform%2Frest%2F\&utm_medium=302#api-group-Issues), and [Managing Project Permissions](https://confluence.atlassian.com/adminjiracloud/managing-project-permissions-776636362.html#Managingprojectpermissions-Projectpermissionsoverview).
* 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](https://confluence.atlassian.com/adminjiraserver071/configuring-the-base-url-802593107.html) 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](https://confluence.atlassian.com/adminjiraserver/running-jira-applications-over-ssl-or-https-938847764.html).
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](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/) from Atlassian. Once you create the scoped API token, add it as a [Harness text secret](/harness-platform/use-harness-platform/secrets/add-use-text-secrets.md). For a YAML example of this credential type, go to [Connector YAML examples](#connector-yaml-examples).\
To find your Cloud ID, go to [Atlassian's guide on finding your Cloud ID](https://support.atlassian.com/jira/kb/retrieve-my-atlassian-sites-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](#connector-yaml-examples).\
To create a PAT, go to [Using Personal Access Tokens](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html) from Atlassian.
3. Click **Continue**.
{% hint style="info" %}
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](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html).
{% endhint %}
### 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
```yaml
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
```yaml
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](https://developer.harness.io/docs/continuous-delivery/x-platform-cd-features/cd-steps/ticketing-systems/create-jira-issues-in-cd-stages/): Create Jira issues from a Continuous Delivery stage.
* [Update Jira issues in CD stages](https://developer.harness.io/docs/continuous-delivery/x-platform-cd-features/cd-steps/ticketing-systems/update-jira-issues-in-cd-stages/): Update existing Jira issues from a Continuous Delivery stage.
* [Adding Jira Approval Stages and Steps](/harness-platform/use-harness-platform/approvals/adding-jira-approval-stages.md): Use Jira issues to gate pipeline approvals.
{% @harness-feedback/feedback module="harness-ai" pagePath="harness-ai/use-harness-platform/connectors/ticketing-systems/connect-to-jira" %}