Skip to content

Commit ee75d88

Browse files
alai97Harness
alai97
authored and
Harness
committed
SEI-15502 Update Connect with Jira Cloud Documentation (#100898)
* 997615 Add Remaining Permissions * 154880 SME Review * 19ee8a Fix Links * 920549 SEI-15502
1 parent 0a0c368 commit ee75d88

File tree

2 files changed

+69
-66
lines changed

2 files changed

+69
-66
lines changed

‎docs/software-engineering-insights/propelo-sei/setup-sei/configure-integrations/static/jira-cloud-type.png‎

-26.8 KB
Loading

‎docs/software-engineering-insights/shared/integrations/jira.mdx‎

Lines changed: 69 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -16,48 +16,86 @@ import TabItem from '@theme/TabItem';
1616

1717
Jira is a proprietary issue-tracking product that allows bug tracking and agile project management. You can connect Harness SEI to Jira using a Harness Jira integration.
1818

19-
### Authenticate with Jira
19+
## Authenticate with Jira
2020

21-
Before you configure the SEI Jira integration, you must generate an Atlassian API token.
21+
Before you configure the SEI Jira integration, [create a classic API token without scopes](https://id.atlassian.com/manage-profile/security/api-tokens) for a Jira Cloud user account. For more information, see the [official Jira documentation](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/).
2222

23-
:::tip Use a service account
24-
The user creating the token must have read access to all projects that you want SEI to track, and the user must be able to search issues within the SEI-relevant projects.
23+
:::tip Use a Jira user account
24+
The user creating the token must have the **Browse Projects**, **View Aggregated Data**, **Browse Users**, and **User Picker** [permissions](https://support.atlassian.com/jira/kb/how-to-determine-project-visibility-in-jira-cloud-using-user-permissions/) for all projects that you want SEI 2.0 to track and search issues within relevant projects.
2525

26-
Due to the scope of visibility required, consider using a managed service account, rather than a personal user account, to create the token.
26+
Use a Jira user account with a classic API token without scopes. Scoped API tokens are not supported.
27+
28+
Service accounts cannot be used to authenticate the SEI Jira integration. The API token must be generated from a standard Jira user account with the required permissions.
2729
:::
2830

29-
1. Create an Atlassian API token. For instructions, go to the Atlassian documentation on [Managing API tokens for your Atlassian account](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/).
30-
2. Make sure to copy the token somewhere that you can retrieve it when you configure the integration.
31+
<img src={apiToken} alt="API Token" width="600" />
3132

32-
<img src={apiToken} alt="API Token" width="500" />
33+
Make sure to copy the token somewhere that you can retrieve it when you configure the integration.
3334

3435
:::info
3536
If you have enabled an allow list in your Atlassian account, certain Harness IP addresses must be added to it in order to allow communication between the Harness Platform and Atlassian. If the necessary IPs are not whitelisted, the integration may fail to authenticate or sync data properly.
3637

37-
To ensure your integration can work correctly, please refer to the list of [Harness Platform IPs](/docs/platform/references/allowlist-harness-domains-and-ips) that may need to be whitelisted in your firewall.
38+
To ensure your integration can work correctly, refer to the list of [Harness Platform IPs](/docs/platform/references/allowlist-harness-domains-and-ips) that may need to be whitelisted in your firewall.
3839
:::
3940

40-
### Add the Jira integration
41+
## Add the Jira by Atlassian integration
42+
43+
To integrate with Jira Cloud in SEI 2.0:
44+
45+
1. From the SEI navigation menu, navigate to **Account Management** > **Integrations** under **Data Settings**.
46+
1. Navigate to the **Available Integrations** tab, locate the **Jira by Atlassian** integration, and click **Add Integration**.
47+
1. Select a Jira type: [Jira Software Cloud](#add-the-jira-integration) or [Jira Data Center](/docs/software-engineering-insights/harness-sei/setup-sei/configure-integrations/jira/jira-data-center).
48+
49+
<img src={jiraType} alt="JIRA Type" width="600" />
50+
51+
1. If you select **Jira Software Cloud**, you can click **Using Jira API Token** or **Using Jira Connect App** (deprecated).
52+
53+
:::info Using Jira API Token
54+
Harness recommends using token-based authentication to integrate Jira Cloud with SEI 2.0. The Jira Connect App–based integration has been deprecated and should only be used for existing setups.
55+
:::
56+
57+
<br />
58+
<img src={cloudType} alt="Jira Cloud Type" width="600" />
59+
60+
<Tabs queryString="jira-cloud-type">
61+
<TabItem value="api-key" label="Using Jira API Token">
4162

42-
To integrate SEI with Jira, you must choose your Jira type:
63+
:::warning Reauthenticate Jira Cloud Using a Token-based Integration
64+
The **Using Jira Connect App** method is no longer supported. You can re-authenticate the Jira Cloud integration by using a [classic unscoped API token](#authenticate-with-jira). Scoped API tokens are not supported.
4365

44-
* [Jira Cloud](#add-the-jira-integration)
45-
* [Jira Data Center](/docs/software-engineering-insights/propelo-sei/setup-sei/configure-integrations/jira/jira-data-center)
66+
The token must be created for a Jira user account. The user account must have the **Browse Projects**, **View Aggregated Data**, **Browse Users**, and **User Picker** [permissions](https://support.atlassian.com/jira/kb/how-to-determine-project-visibility-in-jira-cloud-using-user-permissions/) to be able to read/search issues and access all Jira projects you want SEI 2.0 to track. Service accounts are not supported.
67+
:::
4668

47-
<img src={jiraType} alt="JIRA Type" width="600" />
69+
To set up the integration using a Jira API token:
4870

49-
For the Jira type as Cloud, you can choose how you want to connect Jira, i.e.:
71+
1. Select the **Using Jira API Token** tile to set up the connection with Jira.
72+
1. Configure the integration settings in the **Overview** section:
73+
* Add a name for the integration.
74+
* Optionally, add a description for the integration.
75+
* Optionally, add tags for the integration.
76+
1. Click **Next**.
77+
1. Provide the Jira Cloud credentials in the **Configure Jira Authentication** section:
78+
* Add the **URL** of your **Jira** integration instance, for example, `"https://organization.atlassian.net"`.
79+
* Enter the email address associated with your Atlassian user account.
80+
* Provide the API token generated for that account.
5081

51-
* Jira Connect App
52-
* Jira API Token
82+
<img src={apiKeyCloud} alt="API Key " width="600" />
83+
1. Click **Validate Credentials**.
84+
1. Configure the advanced integration settings if required:
85+
* Select your preferred **Time Zone** from the available options.
86+
* Choose the fields you wish to exclude from ingestion.
87+
88+
You might exclude fields containing sensitive information such as **Summary**, **Description**, and **Comments**. Excluded fields will not be evaluated for hygiene or adherence to best practices.
89+
90+
<img src={jiraKeyConfig} alt="Jira Key Configuration" width="600" />
5391

54-
<img src={cloudType} alt="Jira Cloud Type" width="600" />
92+
1. Click on **Validate Connection** to validate the connection, and once successful, you'll have the integration set up under the **Your Integrations** tab.
5593

56-
<Tabs>
57-
<TabItem value="jira-connect-app" label="Using Jira Connect App" default>
94+
</TabItem>
95+
<TabItem value="jira-connect-app" label="Using Jira Connect App (Deprecated)" default>
5896

59-
:::info Jira Connect App
60-
For organizations that have [deprecated Connect Apps](https://www.atlassian.com/blog/developer/announcing-connect-end-of-support-timeline-and-next-steps), see the **Using Jira API Token** tab to connect Jira Cloud.
97+
:::danger Use Jira API Token Instead
98+
[Jira Connect App](https://www.atlassian.com/blog/developer/announcing-connect-end-of-support-timeline-and-next-steps) is no longer supported. For existing organizations using the Jira Connect App method, see the **Using Jira API Token** tab to re-authenticate Jira Cloud with a token-based integration.
6199
:::
62100

63101
The Jira Connect App facilitates a seamless connection to Jira projects with minimal user intervention, requiring Jira admin configuration for the app.
@@ -74,18 +112,15 @@ The following permissions are required to configure the **Jira Connect App** int
74112

75113
To set up the integration using the **Jira Connect App**:
76114

77-
1. Select **Integrations** under **Data Settings**.
78-
2. Select **Available Integrations**, locate the **Jira integration**, and select **Install**.
79-
3. Select **Jira Software Cloud** as the integration type.
80-
4. Select the **Jira Connect App** tile to set up the connection with Jira.
81-
5. In the Jira Connect App settings page add the basic overview information:
115+
1. Select the **Jira Connect App** tile to set up the connection with Jira.
116+
1. In the Jira Connect App settings page, add the basic overview information:
82117
* **Integration Name:** Name for your integration.
83118
* **Description (optional):** Add a description for the integration.
84119
* **Tags (optional):** Add tags for the integration if required.
85120

86121
<img src={connectConfiguration} alt="Connect Configuration" width="700" />
87122

88-
6. Install the Jira Connect App. To do this, follow these simple steps:
123+
1. Install the Jira Connect App. To do this, follow these simple steps:
89124
* Verify that you are an owner of the Jira account where you track issues. An easy way to check is to visit your organization page and verify that the organization is listed.
90125
* Go to the **Atlassian Marketplace** to install the app and configure the [SEI app](https://marketplace.atlassian.com/apps/1231375/harness-software-engineering-insights-sei?tab=overview\&hosting=cloud) to access the Jira projects.
91126
* **Install** the App.
@@ -110,51 +145,19 @@ To set up the integration using the **Jira Connect App**:
110145
The key expires after 10 minutes, so generate a new key if the current one expires.
111146
:::
112147

113-
7. Click on **Validate Connection** to validate the connection, and once successful, you'll have the integration set up under the **Your Integrations** tab.
114-
115-
</TabItem>
116-
117-
<TabItem value="api-key" label="Using Jira API Token">
118-
119-
Before you configure the SEI Jira integration, you must generate an Atlassian API token.
120-
121-
To set up the integration using the Jira API Token:
122-
123-
1. Select **Integrations** under **Data Settings**.
124-
2. Select **Available Integrations**, locate the **Jira integration**, and select **Install**.
125-
3. Select Jira Software Cloud as the integration type.
126-
4. Select the Using Jira API Token tile to set up the connection with Jira.
127-
5. Configure the integration settings and authentication:
128-
* Integration Name: Name for your integration.
129-
* Description (optional): Add a description for the integration.
130-
* Tags (optional): Add tags for the integration if required.
131-
* Add the **URL** of your **Jira** integration instance, for example, `"https://organization.atlassian.net"`. Make sure it's a valid URL.
132-
* Enter your Email address for the Atlassian account
133-
* Provide the **API Key** that you previously generated for your Atlassian account.
134-
135-
<img src={apiKeyCloud} alt="API Key " width="600" />
136-
137-
7. Configure the advanced integration settings if required:
138-
* Select your preferred **Time Zone** from the available options.
139-
* Choose the fields you wish to exclude from ingestion.
140-
141-
You might exclude fields containing sensitive information such as **Summary**, **Description**, and **Comments**. Excluded fields will not be evaluated for hygiene or adherence to best practices.
142-
143-
<img src={jiraKeyConfig} alt="Jira Key Configuration" width="600" />
144-
145-
8. Click on **Validate Connection** to validate the connection, and once successful, you'll have the integration set up under the **Your Integrations** tab.
148+
1. Click **Validate Connection** to validate the connection, and once successful, you'll have the integration set up under the **Your Integrations** tab.
146149

147150
</TabItem>
148151
</Tabs>
149152

150153
:::info
151-
After adding an integration, it may take up to 24 hours for the data to reflect on Harness SEI. This means that any widgets you configure on the Insights page using this integration may not display data until the synchronization is completed.
154+
After adding an integration, it may take up to 24 hours for the data to reflect in Harness SEI. This means that any widgets you configure on the Insights page using this integration may not display data until the synchronization is completed.
152155
:::
153156

154-
### See also
157+
## Further Reading
155158

156-
* [Connect with Jira Data Center](/docs/software-engineering-insights/propelo-sei/setup-sei/configure-integrations/jira/jira-data-center)
157-
* [Add custom hygiene misses](/docs/software-engineering-insights/propelo-sei/setup-sei/configure-integrations/jira/custom-hygiene-misses)
158-
* [Configure custom field mapping](/docs/software-engineering-insights/propelo-sei/setup-sei/configure-integrations/jira/custom-fields)
159+
* [Connect with Jira Data Center](/docs/software-engineering-insights/harness-sei/setup-sei/configure-integrations/jira/jira-data-center)
160+
* [Add custom hygiene misses](/docs/software-engineering-insights/harness-sei/setup-sei/configure-integrations/jira/custom-hygiene-misses)
161+
* [Configure custom field mapping](/docs/software-engineering-insights/harness-sei/setup-sei/configure-integrations/jira/custom-fields)
159162
* [Reauthenticate](/docs/software-engineering-insights/propelo-sei/setup-sei/configure-integrations/reauthenticate-integration)
160163
* [Ingested data](/docs/software-engineering-insights/propelo-sei/setup-sei/configure-integrations/jira/sei-jira-datasheet)

0 commit comments

Comments
 (0)