docs(jira): document enabling the Jira integration in System Settings (#15381)

The Jira integration is off by default, and while it is off DefectDojo
hides every other Jira control: the Jira menu in the sidebar, the Jira
sections on the Product / Engagement forms, and the push-to-Jira actions,
columns and filters on Findings. Both Jira guides mentioned the toggle
only in passing, so users had no way to tell why the settings they were
reading about were missing.

Add a "Step 1: Enable the Jira integration in System Settings" section to
the OS and Pro guides, with screenshots of the before / after state, what
the setting reveals, and the note that the setting also gates pushes made
through the API and incoming webhooks. The OS guide additionally covers
the webhook secret the classic form requires when the integration is
enabled. Remaining steps are renumbered accordingly.

Also add a troubleshooting entry for "I can't find any Jira settings in
DefectDojo" covering both the setting and the View Jira Instance
configuration permission, and correct the OS guide's webhook section,
which pointed at the Pro sidebar path and reused a Pro UI screenshot.

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: Maffooch

docs/assets/images/jira-asset-settings-visible-os.png

@@ -11,14 +11,56 @@ DefectDojo's Jira integration can be used to push Finding data to one or more Ji
 * DefectDojo can selectively push Findings from separate Products &/or Engagements to separate Jira Spaces, to keep things in their proper context.
 
 # Setting Up Jira
+
 Setting Up Jira requires the following steps:
-1. Connect a Jira Instance, either with a username / password or an API token.  Multiple instances can be linked.
-2. Add that Jira Instance to one or more Products or Engagements within DefectDojo.
-3. If you wish to use bidirectional sync, create a Jira Webhook which will send updates to DefectDojo.
+1. Enable the Jira integration in System Settings.  Until you do, the rest of the Jira settings are hidden throughout DefectDojo.
+2. Connect a Jira Instance, either with a username / password or an API token.  Multiple instances can be linked.
+3. Add that Jira Instance to one or more Products or Engagements within DefectDojo.
+4. If you wish to use bidirectional sync, create a Jira Webhook which will send updates to DefectDojo.
+
+## Step 1: Enable the Jira integration in System Settings
+
+The Jira integration is off by default, and while it is off DefectDojo hides every other Jira control in the interface.  This is the first thing to configure: none of the steps below are available until it is enabled.
+
+While the integration is disabled, the ⚙️ **Configuration \> JIRA** entry is not present in the sidebar, so there is nowhere to add a Jira Instance:
+
+![image](images/jira-config-menu-hidden-os.png)
+
+### Enable the integration
+
+1. Navigate to ⚙️ **Configuration \> System Settings** from the DefectDojo sidebar.
+​
+2. Check **Enable JIRA integration**.
+​
+3. A **Jira webhook secret** is required as soon as the integration is enabled.  Click the 🔄 icon next to the field to generate one.  If you submit the form without a secret, the form is rejected with *"This field is required when enable Jira Integration is True"*:
+
+![image](images/jira-webhook-secret-required-os.png)
+
+The secret is part of the webhook URL that Jira posts to (`https://<YOUR DOJO DOMAIN>/jira/webhook/<SECRET>`), so treat the generated value as a credential.  You only need to hand it to Jira if you set up bidirectional sync in [Step 4](#step-4-configure-bidirectional-sync-jira-webhook); generating it now simply satisfies the form.
+
+4. Click **Submit**.  ⚙️ **Configuration \> JIRA** now appears in the sidebar:
+
+![image](images/jira-enable-system-settings-os.png)
+
+### What the setting controls
+
+Enabling **Enable JIRA integration** is what makes the rest of the Jira interface appear.  With it turned on you get:
+
+* the ⚙️ **Configuration \> JIRA** page, where Jira Instances are added and edited
+* the **JIRA** section on the Edit Product (Asset) and Edit Engagement forms, used to link a Product or Engagement to a Jira Space
+* the **Push to Jira** controls on Findings, Finding Groups and bulk edit forms, plus the Jira columns and filters on the Findings, Engagements and Products lists
+
+For example, the **JIRA** section only appears at the bottom of the Edit Product form once the integration is enabled:
+
+![image](images/jira-asset-settings-visible-os.png)
+
+The setting also gates the integration outside the UI: while it is off, DefectDojo will not push Findings to Jira (including `push_to_jira` requests sent through the API), and incoming Jira webhooks are ignored.
+
+The remaining Jira fields on the System Settings page (**Enable JIRA web hook**, **Jira minimum severity**, **Jira labels**, **Add vulnerability Id as a JIRA label**) stay visible whether the integration is on or off, but they have no effect until it is enabled.
 
-## Step 1: Connect a Jira Instance
+## Step 2: Connect a Jira Instance
 
-Connecting a Jira Instance is the first step to take when setting up DefectDojo's Jira integration.  Please note Jira Service Management is currently not supported.
+With the integration enabled, connecting a Jira Instance is the next step in setting up DefectDojo's Jira integration.  Please note Jira Service Management is currently not supported.
 
 #### Required information from Jira
 
@@ -43,7 +85,7 @@ Multiple Jira Spaces can be handled by a single Jira Instance connection, as lon
 
 ### Add a Jira Instance
 
-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.
+1. Make sure **Enable JIRA integration** is checked in System Settings, as described in [Step 1](#step-1-enable-the-jira-integration-in-system-settings).  The ⚙️ **Configuration \> JIRA** option does not appear on the sidebar until it is.
 ​
 2. Navigate to the ⚙️ **Configuration \> JIRA**  page from the DefectDojo sidebar.
 ​
@@ -113,7 +155,7 @@ Visit `https://<YOUR JIRA URL>/rest/api/latest/issue/<ANY VALID ISSUE KEY>/trans
 
 Comments (in Jira) and Notes (in DefectDojo) can be kept in sync. This setting can be enabled once the Jira configuration has been added to a Product, via the **Edit Product** form.
 
-## Step 2: Connect a Product or Engagement to Jira
+## Step 3: Connect a Product or Engagement to Jira
 
 Each Product or Engagement in DefectDojo has its own settings which govern how Findings are converted to JIRA Issues. From here, you can decide the associated Jira Space and set the default behaviour for creating Issues, Epics, Labels and other JIRA metadata.
 
@@ -236,21 +278,21 @@ The Edit Engagement page can be found from the Engagement page, by clicking the
 
 ![image](images/Creating_Issues_in_Jira_5.png)
 
-## Step 3: Configure Bidirectional Sync: Jira Webhook
+## Step 4: Configure Bidirectional Sync: Jira Webhook
 
 The Jira integration allows for bidirectional sync via webhook. DefectDojo receives Jira notifications at a unique address, which can allow for Jira comments to be received on Findings, or for Findings to be resolved via Jira depending on your configuration.
 
 ### Locating your Jira Webhook URL
 
-Your Jira Webhook is located on the System Settings form under **Jira Integration Settings**: **Enterprise Settings \> System Settings** from the sidebar.
+Your Jira Webhook is made up of your DefectDojo URL and the **Jira webhook secret** you generated in [Step 1](#step-1-enable-the-jira-integration-in-system-settings).  Both are shown on the ⚙️ **Configuration \> System Settings** page, next to the **Jira webhook secret** field (see the screenshot in Step 1).
 
-![image](images/Configuring_the_Jira_DefectDojo_Webhook.png)
+You also need to check **Enable JIRA web hook** on the same page before DefectDojo will process incoming Jira notifications.  Incoming webhooks are ignored if either that box or **Enable JIRA integration** is unchecked.
 
 ### Creating the Jira Webhook
 
 1. Visit `**https:// \<YOUR JIRA URL\> /plugins/servlet/webhooks**`
 2. Click 'Create a Webhook'.
-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.
+3. For the field labeled 'URL' enter: `https:// \<**YOUR DOJO DOMAIN**\> /jira/webhook/ \<**YOUR GENERATED WEBHOOK SECRET**\>`. The Web Hook Secret is listed next to the **Jira webhook secret** field as listed above.
 4. Under 'Comments' enable 'Created'. Under Issue enable 'Updated'.
 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/)
 

docs/assets/images/jira-config-menu-hidden-os.png

@@ -13,14 +13,46 @@ DefectDojo's Jira integration can be used to push Finding data to one or more Ji
 * DefectDojo can selectively push Findings from separate Products &/or Engagements to separate Jira Spaces, to keep things in their proper context.
 
 # Setting Up Jira
+
 Setting Up Jira requires the following steps:
-1. Connect a Jira Instance, either with a username / password or an API token.  Multiple instances can be linked.
-2. Add that Jira Instance to one or more Products or Engagements within DefectDojo.
-3. If you wish to use bidirectional sync, create a Jira Webhook which will send updates to DefectDojo.
+1. Enable the Jira integration in System Settings.  Until you do, the rest of the Jira settings are hidden throughout DefectDojo.
+2. Connect a Jira Instance, either with a username / password or an API token.  Multiple instances can be linked.
+3. Add that Jira Instance to one or more Products or Engagements within DefectDojo.
+4. If you wish to use bidirectional sync, create a Jira Webhook which will send updates to DefectDojo.
+
+## Step 1: Enable the Jira integration in System Settings
+
+The Jira integration is off by default, and while it is off DefectDojo hides every other Jira control in the interface.  This is the first thing to configure: none of the steps below are available until it is enabled.
+
+While the integration is disabled, there is no **Jira Instances** entry in the sidebar, so there is nowhere to add a Jira Instance:
+
+![image](images/jira-menu-hidden-pro.png)
+
+### Enable the integration
+
+1. Navigate to **\<Your Edition\> Settings \> System Settings** from the DefectDojo sidebar.  The menu is named after your license package, so it reads **Pro Settings** on a Pro instance and **Enterprise Settings** on an Enterprise instance.
+​
+2. In the **Jira Integration Settings** section, check **Enable Jira Integration**.
+​
+3. Click **Submit**.  **Jira Instances** appears in the sidebar immediately, without reloading the page:
+
+![image](images/jira-enable-system-settings-pro.png)
+
+### What the setting controls
+
+Enabling **Enable Jira Integration** is what makes the rest of the Jira interface appear.  With it turned on you get:
 
-## Step 1: Connect a Jira Instance
+* the **Jira Instances** menu, where Jira Instances are added and edited
+* the **Jira Project Settings** page on the Asset ⚙️ menu, and the Jira settings on Engagements
+* the **Push to Jira** actions on Findings and Finding Groups, the Jira fields on the Finding and bulk edit forms, and the Jira columns on the Asset, Engagement, Finding and Finding Group lists (including CSV exports)
 
-Connecting a Jira Instance is the first step to take when setting up DefectDojo's Jira integration.  Please note Jira Service Management is currently not supported.
+The setting also gates the integration outside the UI: while it is off, DefectDojo will not push Findings to Jira (including `push_to_jira` requests sent through the API), and incoming Jira webhooks are ignored.
+
+The remaining Jira fields in **Jira Integration Settings** (**Add Vulnerability ID as Jira Label**, **Enable Jira Web Hook**, **Disable Jira Web Hook Secret**, **Jira Web Hook Secret**, **Jira Minimum Severity**) stay visible whether the integration is on or off, but they have no effect until it is enabled.
+
+## Step 2: Connect a Jira Instance
+
+With the integration enabled, connecting a Jira Instance is the next step in setting up DefectDojo's Jira integration.  Please note Jira Service Management is currently not supported.
 
 #### Required information from Jira
 
@@ -46,7 +78,7 @@ Multiple Jira Spaces can be handled by a single Jira Instance connection, as lon
 
 ### Add a Jira Instance
 
-1. If you have not already done so, navigate to the System Settings page and check the box on **Enable Jira Integration**.
+1. Make sure **Enable Jira Integration** is checked in System Settings, as described in [Step 1](#step-1-enable-the-jira-integration-in-system-settings).  The **Jira Instances** menu does not appear on the sidebar until it is.
 
 2. Navigate to the  **Enterprise Settings \> Jira Instances \> + New Jira Instance**  page from the DefectDojo sidebar.
 
@@ -82,7 +114,7 @@ If you leave this field blank, it will default to **Jira\_full.**  If you need a
 
 The form can be submitted from here.  If you wish, you can further customize your Jira integration under Optional Fields.  Clicking this button will allow you to apply generic text to Jira Issues or change the mapping of Jira Severity Mappings.
 
-## Step 2: Connect a Product or Engagement to Jira
+## Step 3: Connect a Product or Engagement to Jira
 
 Each Product or Engagement in DefectDojo has its own settings which govern how Findings are converted to JIRA Issues. From here, you can decide the associated Jira Space and set the default behaviour for creating Issues, Epics, Labels and other JIRA metadata.
 
@@ -235,14 +267,16 @@ Note that once an Engagement has its own Jira project assigned, it can no longer
 
 ![image](images/Creating_Issues_in_Jira_5.png)
 
-## Step 3: Configure Bidirectional Sync: Jira Webhook
+## Step 4: Configure Bidirectional Sync: Jira Webhook
 
 The Jira integration allows for bidirectional sync via webhook. DefectDojo receives Jira notifications at a unique address, which can allow for Jira comments to be received on Findings, or for Findings to be resolved via Jira depending on your configuration.
 
 ### Locating your Jira Webhook URL
 
 Your Jira Webhook is located on the System Settings form under **Jira Integration Settings**: **Enterprise Settings \> System Settings** from the sidebar.
 
+You also need to check **Enable Jira Web Hook** on the same page before DefectDojo will process incoming Jira notifications.  Incoming webhooks are ignored if either that box or **Enable Jira Integration** (see [Step 1](#step-1-enable-the-jira-integration-in-system-settings)) is unchecked.
+
 ![image](images/Configuring_the_Jira_DefectDojo_Webhook.png)
 
 ### Creating the Jira Webhook

docs/assets/images/jira-enable-system-settings-os.png

@@ -8,6 +8,17 @@ aliases:
 
 Here are some common issues with the Jira integration, and ways to address them.
 
+## I can't find any Jira settings in DefectDojo
+
+If there is no Jira menu in the sidebar, no Jira section on the Product / Engagement forms, and no **Push to Jira** option on Findings, the Jira integration is most likely still disabled in System Settings.  DefectDojo hides every Jira control until it is turned on.
+
+Check **Enable Jira Integration** on the System Settings page:
+
+* Open Source: ⚙️ **Configuration \> System Settings**, then check **Enable JIRA integration**.  A **Jira webhook secret** is also required before the form will save, so click the 🔄 icon to generate one.  See the [Jira Integration Guide](/issue_tracking/jira/os__jira_guide/#step-1-enable-the-jira-integration-in-system-settings).
+* Pro: **\<Your Edition\> Settings \> System Settings**, then check **Enable Jira Integration** under **Jira Integration Settings**.  See the [Jira Integration Guide](/issue_tracking/jira/pro__jira_guide/#step-1-enable-the-jira-integration-in-system-settings).
+
+If the setting is already enabled and you still can't see the Jira menu, your user may be missing the **View Jira Instance** Configuration Permission, which is also required for the menu to appear.  It can be assigned directly on the User page or through a User Group.  See [About Permissions and Roles](/admin/user_management/about_perms_and_roles/#configuration-permissions).
+
 ## DefectDojo cannot reach Jira (or other outbound services) at all
 
 If DefectDojo's Jira integration fails with connection errors that look like "connection refused", "no route to host", or generic TLS handshake failures — and the credentials themselves are valid — your DefectDojo instance may be behind a firewall that requires outbound traffic to go through a forward HTTPS proxy.