diff --git a/docs/semgrep-appsec-platform/jira.md b/docs/semgrep-appsec-platform/jira.md index 33e85356f0..ffd0b8f3b8 100644 --- a/docs/semgrep-appsec-platform/jira.md +++ b/docs/semgrep-appsec-platform/jira.md @@ -27,14 +27,13 @@ The Semgrep Jira integration allows you to create Jira tickets based on your Sem The Semgrep Jira integration provides the following capabilities: - You can create tickets for findings from Semgrep Code, Supply Chain, and Secrets. -- You can create a single ticket for multiple findings (up to 50) that were detected by a single rule in the same project, or create individual tickets per finding. +- You can create a single ticket for multiple findings (up to 75) that were detected by a single rule in the same project, or create individual tickets per finding. - You can automate the creation of tickets for high severity, high confidence findings in your [primary branch](/deployment/primary-branch). - Automated ticket creation can be configured on a per-product setting. - For Supply Chain findings, tickets are created for reachable findings. - Tickets are automatically created for **new** findings generated by scans that occur **after** enabling automated ticket creation. Tickets are not automatically created for existing findings. - Tickets can be created in **multiple Jira projects** if manually specified at ticket creation time. - ## Limitations - You can only create **one Jira integration** per Semgrep account or deployment. @@ -49,6 +48,7 @@ To enable the Jira integration, follow these steps: 2. Navigate to [**Settings** > **Integrations**](https://semgrep.dev/orgs/-/settings/integrations). 3. If this is your first integration, click **Set up First Integration**. Otherwise, click **Add**. In the drop-down menu that appears, select **Jira**. 4. Follow the on-screen instructions to grant Semgrep the necessary permissions and set up the integration. + * In order for Semgrep to perform necessary actions in Jira, you must grant the following permissions: `read:jira-work`, `write:jira-work`, and `manage:jira-configuration`. 5. When prompted, select the Jira instance you want to connect to. If you have multiple Jira instances, choose one instance from the **Use app on** drop-down menu. * **For deployments that have used a previous version of the Jira integration**: Ensure you're connecting to the same Jira instance you previously connected to. Please contact Semgrep if you want to connect to a different Jira instance. @@ -274,6 +274,53 @@ _**Figure.** Secrets triage flow._ ![Jira ticket created - Semgrep Secrets](/img/jira-secrets-ticketed.png#md-width) _**Figure.** Secrets ticket created._ +## One-way sync from Semgrep to Jira (beta) + +One-way sync allows Semgrep to update the Jira ticket associated with a finding when Semgrep determines that you have fixed the finding. + +:::info +One-way sync is currently in **private beta**. Please contact [Support](/support) for access to this feature. +::: + +### Enable one-way sync for new integrations + +To set up one-way sync from Semgrep to Jira: + +1. Sign in to [ Semgrep AppSec Platform](https://semgrep.dev/login). +2. Navigate to [**Settings** > **Integrations**](https://semgrep.dev/orgs/-/settings/integrations). +3. [Enable a Jira integration](#enable-the-jira-integration) for your Semgrep organization. +4. Expand **Customize ticket creation** and locate the **Jira Sync** section. +5. Select the workflow action that you have set up in Jira using the drop-down menu to set the change that happens after a sync is triggered. + ![New Setup Card](/img/jira-sync-setup-card.png#md-width) +6. Select the transition, or change, that you want to occur when a sync is triggered. Note that, if you select **None Selected** as the transition option, **no transition** is triggered. + ![Drop Down expanded](/img/jira-sync-transition-expanded.png) +7. Click **Save**. + +### Enable one-way sync for existing integrations + +:::info +Before proceeding, ensure that you have [enabled a Jira integration](#enable-the-jira-integration) for your Semgrep organization. +::: + +If you have an existing Jira integration configured, you must reauthorize Jira to enable one-way sync. This step is necessary because Semgrep requires an additional permission `manage:jira-configuration` to retrieve and trigger Jira transitions. + +1. Sign in to [ Semgrep AppSec Platform](https://semgrep.dev/login). +1. Navigate to [**Settings** > **Integrations**](https://semgrep.dev/orgs/-/settings/integrations). +2. Find your Jira integration, then expand **Customize ticket creation** so that you can locate the **Jira Sync** section. +3. Click **Re-authorize to enable Jira Sync**. + +:::note One-way sync limitations +Currently, the following limitations apply to one-way sync: + +- One-way sync only works with Semgrep Code findings with a status of **Fixed**. +- The only items synced are those with a 1:1 mapping between the Semgrep finding and the Jira ticket. +- Only the default project and issue types are supported. +- Team-managed projects are supported for all users. + - Company-managed projects are supported only if your Jira administrator set up the Semgrep Jira integration initially. +- You can only trigger one [Jira transition](https://support.atlassian.com/jira-software-cloud/docs/transition-an-issue/). + - If your selected transition is removed in Jira, Semgrep is unable to sync or replay any sync attempts while the transition is removed. +::: + ## Create tickets through the Semgrep API Semgrep provides an API endpoint you can use to create Jira tickets, either by passing a list of `issue_ids` or filter query parameters to select findings. Refer to the [ Jira API documentation](https://semgrep.dev/api/v1/docs/#tag/TicketingService/operation/semgrep_app.core_exp.notifications.ticketing.handlers.openapi_create_tickets). diff --git a/static/img/jira-sync-reauth.png b/static/img/jira-sync-reauth.png new file mode 100644 index 0000000000..8fcdbc29fd Binary files /dev/null and b/static/img/jira-sync-reauth.png differ diff --git a/static/img/jira-sync-setup-card.png b/static/img/jira-sync-setup-card.png new file mode 100644 index 0000000000..6015d8efe2 Binary files /dev/null and b/static/img/jira-sync-setup-card.png differ diff --git a/static/img/jira-sync-transition-expanded.png b/static/img/jira-sync-transition-expanded.png new file mode 100644 index 0000000000..969820fe80 Binary files /dev/null and b/static/img/jira-sync-transition-expanded.png differ