You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/content/en/share_your_findings/jira_integration/connect_to_jira.md
+37-36Lines changed: 37 additions & 36 deletions
Original file line number
Diff line number
Diff line change
@@ -23,21 +23,21 @@ Multiple Jira Projects can be handled by a single Jira Instance connection, as l
23
23
24
24
#### How Findings are pushed
25
25
26
-
Connecting a Jira instance does not cause any Findings to push right away \- this is simply the first step. Once the Jira Instance connection is created, it must be associated with a Product or an Engagement before any information will push to Jira.
26
+
Connecting a Jira instance does not cause any Findings to push right away \- this is simply the first step. Once the Jira Instance connection is created, it must be associated with a Product or an Engagement before any information will push to Jira.
27
27
28
28
If you already have a Jira Instance connection set up, you can use **[this guide](../add_jira_to_product)** for help with adding this integration to a Product.
29
29
30
30
## Add a Jira Instance (Pro UI)
31
31
32
32
1. If you have not already done so, navigate to the System Settings page and check the box on **Enable Jira Integration**.
33
33
34
-
2. Navigate to the **Enterprise Settings \> Jira Instances \> + New Jira Instance** page from the DefectDojo sidebar.
34
+
2. Navigate to the **Enterprise Settings \> Jira Instances \> + New Jira Instance** page from the DefectDojo sidebar.
35
35
36
36
37
37
38
-
3. Select a **Configuration Name** for this Jira Instance to use in DefectDojo. This name is simply a label for the Instance connection in DefectDojo, and does not need to be related to any Jira data.
38
+
3. Select a **Configuration Name** for this Jira Instance to use in DefectDojo. This name is simply a label for the Instance connection in DefectDojo, and does not need to be related to any Jira data.
39
39
40
-
4. Select the URL for your company’s Jira instance \- likely similar to https://**yourcompany**.atlassian.net if you’re using a Jira Cloud installation.
40
+
4. Select the URL for your company’s Jira instance \- likely similar to https://**yourcompany**.atlassian.net if you’re using a Jira Cloud installation.
41
41
42
42
5. Enter an appropriate authetication method in the Username / Password fields for Jira:
43
43
* For standard **username / password Jira authentication**, enter a Jira Username and corresponding Password in these fields.
@@ -47,18 +47,18 @@ If you already have a Jira Instance connection set up, you can use **[this guide
47
47
Note that the user associated with this connection have permission to create Issues and access data in your Jira instance.
48
48
49
49
6. You will need to provide values for an Epic Name ID, Re-open Transition ID and Close Transition ID. These values can be changed later. While logged into Jira, you can access these values from the following URLs:
50
-
-**Epic Name ID**: visit `https://\<YOUR JIRA URL\>/rest/api/2/field` and search for Epic Name. Copy the number out of cf\[number] and paste it here.
51
-
-**Re-open Transition ID**: visit `https://\<YOUR JIRA URL\>/rest/api/latest/issue/\<ANY VALID ISSUE KEY\>/transitions? expand\-transitions.fields` to find the ID for your Jira instance. Paste it in the Reopen Transition ID field.
52
-
-**Close Transition ID**: Visit `https://\<YOUR JIRA URL\>/rest/api/latest/issue/\<ANY VALID ISSUE KEY\>/transitions? expand\-transitions.fields` to find the ID for your Jira instance. Paste it in the Close Transition ID field.
50
+
-**Epic Name ID**: visit `https://\<YOUR JIRA URL\>/rest/api/2/field` and search for Epic Name. Copy the number out of cf\[number] and paste it here.
51
+
-**Re-open Transition ID**: visit `https://\<YOUR JIRA URL\>/rest/api/latest/issue/\<ANY VALID ISSUE KEY\>/transitions? expand\-transitions.fields` to find the ID for your Jira instance. Paste it in the Reopen Transition ID field.
52
+
-**Close Transition ID**: Visit `https://\<YOUR JIRA URL\>/rest/api/latest/issue/\<ANY VALID ISSUE KEY\>/transitions? expand\-transitions.fields` to find the ID for your Jira instance. Paste it in the Close Transition ID field.
53
53
54
54
7. Select the Default issue type which you want to create Issues as in Jira. The options for this are **Bug, Task, Story** and **Epic** (which are standard Jira issue types) as well as **Spike** and **Security**, which are custom issue types. If you have a different Issue Type which you want to use, please contact [support@defectdojo.com](mailto:support@defectdojo.com) for assistance.
55
55
56
56
8. Select your Issue Template, which will determine the Issue Description when Issues are created in Jira.
57
57
58
-
The two types are:
59
-
\-**Jira\_full**, which will include all Finding information in Jira Issues
60
-
\-**Jira\_limited**, which will include a smaller amount of Finding information and metadata.
61
-
58
+
The two types are:
59
+
\-**Jira\_full**, which will include all Finding information in Jira Issues
60
+
\-**Jira\_limited**, which will include a smaller amount of Finding information and metadata.
61
+
62
62
If you leave this field blank, it will default to **Jira\_full.** If you need a different kind of template, Pro users can reach out to support@defectdojo.com
63
63
64
64
9. If you wish, enter the name of a Jira Resolution which will change the status of a Finding to Accepted or to False Positive (when the Resolution is triggered on the Issue).
@@ -67,9 +67,9 @@ The form can be submitted from here. If you wish, you can further customize you
67
67
68
68
## Add a Jira Instance (Legacy UI / Open-Source)
69
69
70
-
1. If you have not already done so, navigate to the System Settings page and check the box on **Enable Jira Integration**. You will need to do this before the ⚙️ **Configuration \> JIRA** option shows up on the sidebar.
70
+
1. If you have not already done so, navigate to the System Settings page and check the box on **Enable Jira Integration**. You will need to do this before the ⚙️ **Configuration \> JIRA** option shows up on the sidebar.
71
71
72
-
2. Navigate to the ⚙️ **Configuration \> JIRA** page from the DefectDojo sidebar.
72
+
2. Navigate to the ⚙️ **Configuration \> JIRA** page from the DefectDojo sidebar.
73
73
74
74
75
75
@@ -83,58 +83,58 @@ The Express method allows for a quicker method of linking a Project. Use the Exp
83
83
84
84
85
85
86
-
1. Select a name for this Jira Configuration to use in DefectDojo. This name is simply a label for the Instance connection in DefectDojo, and does not need to be related to any Jira data.
86
+
1. Select a name for this Jira Configuration to use in DefectDojo. This name is simply a label for the Instance connection in DefectDojo, and does not need to be related to any Jira data.
87
87
88
-
2. Select the URL for your company’s Jira instance \- likely similar to https://**yourcompany**.atlassian.net if you’re using a Jira Cloud installation.
88
+
2. Select the URL for your company’s Jira instance \- likely similar to https://**yourcompany**.atlassian.net if you’re using a Jira Cloud installation.
89
89
90
90
3. Enter an appropriate authetication method in the Username / Password fields for Jira:
91
91
* For standard **username / password Jira authentication**, enter a Jira Username and corresponding Password in these fields.
92
92
* For authentication with a **user's API token (Jira Cloud)** enter the Username with the corresponding **API token** in the password field.
93
93
* For authentication with a Jira **Personal Access Token (aka PAT, used in Jira Data Center and Jira Server only)**, enter the PAT in the password field. Username is not used for authentication with a Jira PAT, but the field is still required in this form, so you can use a placeholder value here to identify your PAT.
94
94
95
-
4. Select the Default issue type which you want to create Issues as in Jira. The options for this are **Bug, Task, Story** and **Epic** (which are standard Jira issue types) as well as **Spike** and **Security**, which are custom issue types. If you have a different Issue Type which you want to use, please contact [support@defectdojo.com](mailto:support@defectdojo.com) for assistance.
95
+
4. Select the Default issue type which you want to create Issues as in Jira. The options for this are **Bug, Task, Story** and **Epic** (which are standard Jira issue types) as well as **Spike** and **Security**, which are custom issue types. If you have a different Issue Type which you want to use, please contact [support@defectdojo.com](mailto:support@defectdojo.com) for assistance.
96
96
97
97
5. Select your Issue Template, which will determine the Issue Description when Issues are created in Jira.
98
98
99
-
The two types are:
100
-
\-**Jira\_full**, which will include all Finding information in Jira Issues
101
-
\-**Jira\_limited**, which will include a smaller amount of Finding information and metadata.
102
-
103
-
If you leave this field blank, it will default to **Jira\_full.**
99
+
The two types are:
100
+
\-**Jira\_full**, which will include all Finding information in Jira Issues
101
+
\-**Jira\_limited**, which will include a smaller amount of Finding information and metadata.
102
+
103
+
If you leave this field blank, it will default to **Jira\_full.**
104
104
105
-
6. Select one or more Jira Resolution types which will change the status of a Finding to Accepted (when the Resolution is triggered on the Issue). If you don’t wish to use this automation, you can leave the field blank.
105
+
6. Select one or more Jira Resolution types which will change the status of a Finding to Accepted (when the Resolution is triggered on the Issue). If you don’t wish to use this automation, you can leave the field blank.
106
106
107
-
7. Select one or more Jira Resolution types which will change the status of a Finding to False Positive (when the Resolution is triggered on the Issue). If you don’t wish to use this automation, you can leave the field blank.
107
+
7. Select one or more Jira Resolution types which will change the status of a Finding to False Positive (when the Resolution is triggered on the Issue). If you don’t wish to use this automation, you can leave the field blank.
108
108
109
-
8. Decide whether you wish to send SLA Notifications as a comment on a Jira issue.
109
+
8. Decide whether you wish to send SLA Notifications as a comment on a Jira issue.
110
110
111
-
9. Decide whether you wish to automatically sync Findings with Jira. If this is enabled, Jira Issues will automatically be kept in sync with the related Findings. If this is not enabled, you will need to manually push any changes made to a Finding after the Issue has been created in Jira.
111
+
9. Decide whether you wish to automatically sync Findings with Jira. If this is enabled, Jira Issues will automatically be kept in sync with the related Findings. If this is not enabled, you will need to manually push any changes made to a Finding after the Issue has been created in Jira.
112
112
113
-
10. Select your Issue key. In Jira, this is the string associated with an Issue (e.g. the word **‘EXAMPLE’** in an issue called **EXAMPLE\-123**). If you don’t know your issue key, create a new Issue in the Jira Project. In the screenshot below, we can see that the issue key on our Jira Project is **DEF**.
113
+
10. Select your Issue key. In Jira, this is the string associated with an Issue (e.g. the word **‘EXAMPLE’** in an issue called **EXAMPLE\-123**). If you don’t know your issue key, create a new Issue in the Jira Project. In the screenshot below, we can see that the issue key on our Jira Project is **DEF**.
114
114
115
115
116
116
117
117
11. Click **Submit.** DefectDojo will automatically look for appropriate mappings in Jira and add them to the configuration. You are now ready to link this configuration to one or more Products in DefectDojo.
118
118
119
119
### Add Jira Configuration (Standard)
120
120
121
-
The Standard Jira Configuration adds a few additional steps to allow for more precise control over Jira mappings and interactions. This can be changed after a Jira configuration has been added, even if it was created using the Express method.
121
+
The Standard Jira Configuration adds a few additional steps to allow for more precise control over Jira mappings and interactions. This can be changed after a Jira configuration has been added, even if it was created using the Express method.
122
122
123
123
### Additional Configuration Options
124
124
125
-
***Epic Name ID:** If you have multiple Epic types in Jira, you can specify the one you want to use by finding its ID in the Jira Field Spec.
126
-
127
-
To obtain the 'Epic name id' visit `https://\<YOUR JIRA URL\>/rest/api/2/field` and search for Epic Name. Copy the number out of cf\[number] and paste it here.
125
+
***Epic Name ID:** If you have multiple Epic types in Jira, you can specify the one you want to use by finding its ID in the Jira Field Spec.
126
+
127
+
To obtain the 'Epic name id' visit `https://\<YOUR JIRA URL\>/rest/api/2/field` and search for Epic Name. Copy the number out of cf\[number] and paste it here.
128
128
129
-
***Reopen Transition ID:** If you want a specific Jira Transition to Reopen an issue, you can specify the Transition ID here. If using the Express Jira Configuration, DefectDojo will automatically find an appropriate Transition and create the mapping.
129
+
***Reopen Transition ID:** If you want a specific Jira Transition to Reopen an issue, you can specify the Transition ID here. If using the Express Jira Configuration, DefectDojo will automatically find an appropriate Transition and create the mapping.
130
+
131
+
Visit `https://\<YOUR JIRA URL\>/rest/api/latest/issue/\<ANY VALID ISSUE KEY\>/transitions? expand\-transitions.fields` to find the ID for your Jira instance. Paste it in the Reopen Transition ID field.
130
132
131
-
Visit `https://\<YOUR JIRA URL\>/rest/api/latest/issue/\<ANY VALID ISSUE KEY\>/transitions? expand\-transitions.fields`to find the ID for your Jira instance. Paste it in the Reopen Transition ID field.
133
+
***Close Transition ID:** If you want a specific Jira Transition to Close an issue, you can specify the Transition ID here. If using the **Express Jira Configuration**, DefectDojo will automatically find an appropriate Transition and create the mapping.
132
134
133
-
***Close Transition ID:** If you want a specific Jira Transition to Close an issue, you can specify the Transition ID here. If using the **Express Jira Configuration**, DefectDojo will automatically find an appropriate Transition and create the mapping.
134
-
135
-
Visit `https://\<YOUR JIRA URL\>/rest/api/latest/issue/\<ANY VALID ISSUE KEY\>/transitions? expand\-transitions.fields` to find the ID for your Jira instance. Paste it in the Close Transition ID field.
135
+
Visit `https://\<YOUR JIRA URL\>/rest/api/latest/issue/\<ANY VALID ISSUE KEY\>/transitions? expand\-transitions.fields` to find the ID for your Jira instance. Paste it in the Close Transition ID field.
136
136
137
-
***Mapping Severity Fields:** Each Jira Issue has an associated Priority, which DefectDojo will automatically assign based on the Severity of a Finding. Enter the names of each Priority which you want to map to, for Info, Low, Medium, High and Critical Severities.
137
+
***Mapping Severity Fields:** Each Jira Issue has an associated Priority, which DefectDojo will automatically assign based on the Severity of a Finding. Enter the names of each Priority which you want to map to, for Info, Low, Medium, High and Critical Severities.
138
138
139
139
***Finding Text**\- if you want to add additional standardized text to each Issue created, you can enter that text here. This is not text that maps to any field in Jira, but additional text that is added to the Issue Description. "**Created by DefectDojo**" for example.
140
140
@@ -156,6 +156,7 @@ Your Jira Webhook is located on the System Settings form under **Jira Integratio
156
156
2. Click 'Create a Webhook'.
157
157
3. For the field labeled 'URL' enter: `https:// \<**YOUR DOJO DOMAIN**\> /jira/webhook/ \<**YOUR GENERATED WEBHOOK SECRET**\>`. The Web Hook Secret is listed under the Jira Integration Settings as listed above.
158
158
4. Under 'Comments' enable 'Created'. Under Issue enable 'Updated'.
159
+
5. Make sure your JIRA instance trusts the SSL certificate used by your DefectDojo instance. For JIRA Cloud DefectDojo must use [a valid SSL/TLS certificate, signed by a globally trusted certificate authority](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-registering-webhooks-with-non-secure-urls/)
159
160
160
161
Note that you do not need to create a Secret within Jira to use this webhook. The Secret is built into DefectDojo's URL, so simply adding the complete URL to the Jira Webhook form is sufficient.
Copy file name to clipboardExpand all lines: docs/content/en/share_your_findings/jira_integration/troubleshooting_jira.md
+4Lines changed: 4 additions & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -26,8 +26,12 @@ This error message can appear when attempting to add a created Jira configuratio
26
26
27
27
* Start by confirming that the [DefectDojo webhook receiver](../connect_to_jira/#configure-bidirectional-sync-jira-webhook) is configured correctly and can successfully receive updates.
28
28
29
+
* Ensure the SSL certificate used by Defect Dojo is trusted by JIRA. For JIRA Cloud you must use [a valid SSL/TLS certificate, signed by a globally trusted certificate authority](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-registering-webhooks-with-non-secure-urls/)
30
+
29
31
* If you're trying to push status changes, confirm that Jira transition mappings are set up correctly (Reopen / Close [Transition IDs](../connect_to_jira/#configure-bidirectional-sync-jira-webhook)).
30
32
33
+
*[Test](https://support.atlassian.com/jira/kb/testing-webhooks-in-jira-cloud/) your JIRA webhook using a public endpoint such as Pipedream or Beeceptor:
34
+
31
35
## Jira Epics aren't being created
32
36
33
37
`"Field 'customfield_xyz' cannot be set. It is not on the appropriate screen, or unknown."`
0 commit comments