DESIGN: Create a Jira issue from vulnerability
Release notes
Problem to solve
Many customers use Jira as their single source of truth for tracking issues and engineering work. When using GitLab for SCM and CI/CD, they can take advantage of our existing integration to pass information from MRs and commits into existing Jira issues. However, there is currently no way to pass information about vulnerabilities detected by security scanners into Jira. This leaves users who rely on Jira to track work no choice but to manually copy vulnerability information into new Jira issues.
Intended users
User experience goal
When Jira integration is properly configured for a project, users can create a new Jira issue from a vulnerability or finding. The experience should be very similar to when creating a GitLab Issue from a vulnerability or finding. We should consider if there needs to be a visual distinction such as changing Create Issue
buttons to Create Jira Issue
instead.
Issues created in Jira need to clearly show the vulnerability details and also be easily identifiable as having come from GitLab. For instance, the Jira issue should have a link back to the GitLab vulnerability. The GitLab vulnerabilities and findings also need to clearly show the relevant Jira issue link.
On the configuration side, it needs to be clear how to setup mapping GitLab projects to Jira projects. It also needs to be straightforward to pick the right Jira issue type—on a per-project basis—to create from a vulnerability. For instance, some users will want to create Jira Stories and some will prefer Jira Bugs.
Proposal
Key points to address:
- Configuration:
- Leverage the instance-level and/or project-level Jira integration settings (for connection settings)
- Limit configuration of vulnerability/Jira mapping to Ultimate / Gold licenses (the main Jira integration is limited to Premium / Silver)
- Direct lower-tier license users to Upgrade, just like main Jira integration does
- Allow GitLab project to Jira project mapping
- Allow setting Jira issue type for creation (ideally check issue type exists)
- Leverage the instance-level and/or project-level Jira integration settings (for connection settings)
- Issue creation:
- Leverage existing UX patterns for creating issues from vulnerabilities
- Determine if it is feasible to also allow creating Jira issues from findings
- Add links to any created Jira issues inside vulnerability (and possibly finding) details, again using existing UX patterns where possible
Further details
This feature needs to work for the currently supported integration combinations of GitLab self-managed, gitlab.com, Jira SaaS, and Jira self-hosted. As project-to-project mapping will be required between the two systems, consider if GitLab Service Templates can be leveraged.
It may not be feasible to handle creating Jira issues from findings as findings are transient entities and do not have a fixed URI like a vulnerability. The creation may work fine but there would be nothing to link back to from the Jira side. Targeting the source MR or pipeline could work but that will lead to a confusing user experience as you then have to locate the relevant finding in a list of all findings.
We also need to think carefully about how we target Jira issue types. There are several default issue types but it is also possible to create custom issue types, which some customers may prefer to use. One suggestion is we ask explicitly for the issue type ID as part of the configuration rather than trying to pull all types or make an assumption. It is probably best to test for existence during configuration. But because there can be custom types, for this MVC, we should avoid creating a field mapping exercise. Therefore, we should populate an issue Description
with the vulnerability title and put the rest of the vulnerability information into the Summary
(https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-fields/#api-rest-api-3-field-get).
The ability to create Jira issues directly from a GitLab object is net-new functionality. This has the potential to introduce confusion as the GitLab issue tracker functionality operates independently from any configured 3rd party issue tracker. In other words, you can leave GitLab issues On
for a project while also using a 3rd party issue tracker as we historically are not creating issues directly in the external trackers.
To help alleviate this confusion, it needs to be very clear that turning on vulnerability → Jira issue creation will take precedence over the GitLab issue tracker for that project—even if it is still enabled.
Error Handling We need to expose errors from Jira to the user in the relevant parts of the GitLab UI to communicate when something didn't go as expected. Otherwise, such errors will be hidden and make troubleshooting very difficult. Areas we need to check for and display error message from Jira include but are not limited to:
- Problems setting or updating the integration configuration such as incorrect Project ID or Jira issue type
- Failure to create a new Jira issue from a vulnerability
For the integration configuration, if it is possible to make read-only calls to Jira to verify the details such as project ID and issue type are correct, we should do that as part of the Save
action. Any errors from Jira should be displayed and the settings should not be saved yet; the user can chose to Cancel
if there are any such errors and the configuration will remain as it was before any changes were attempted.
SCENARIO: I am an authorized user configuring a GitLab project for creating Jira issues from vulnerabilities
WHEN I am enabling Jira issue creation from vulnerabilities in GitLab
THEN I see a clear indication that doing so will ignore or disable GitLab issue creation from vulnerabilities in this project
WHEN GitLab issue tracking is disabled
AND Jira issue creation from vulnerabilities is disabled
THEN I do not see any way to create issues anywhere in this project
WHEN GitLab issue tracking is enabled
AND Jira issue creation from vulnerabilities is disabled
THEN I can create GitLab issues in this project (normal use case)
WHEN GitLab issue tracking is enabled
AND Jira issue creation from vulnerabilities is enabled
THEN I create issues in the configured Jira project from vulnerabilities in this GitLab project
BUT from any other place in the project, I create a GitLab issue (such as from the `+ → New issue` top level menu)
WHEN GitLab issue tracking is disabled
AND Jira issue creation from vulnerabilities is enabled
THEN I can create issues in the configured Jira project from vulnerabilities in this GitLab project
BUT I do not see any other places to create issues—in Jira or GitLab—anywhere else in the project
GIVEN Jira issue creation from vulnerabilities is enabled on my project
WHEN I disable Jira issue creation from vulnerabilities
OR I disable the Jira integration for the project
THEN creating issues from vulnerabilities is determined by GitLab issue tracking status for the project
NOTE: We should consider related use cases such that other groups can leverage this work. The most obvious is creating Jira issues from non-vulnerability places. For instance, using the + → New issue
option could create a new Story directly inside Jira. However, we should not focus too much on broad extensibility at the expense of delivering the necessary functionality needed for vulnerability management integration and outlined above.
Permissions and Security
Only users with permission to access and modify existing Jira integration settings—at the instance or project level—can access the new configuration settings.
Users with access to vulnerabilities or findings are able to create new Jira issues.
Documentation
Availability & Testing
What does success look like, and how can we measure that?
What is the type of buyer?
Is this a cross-stage feature?
Will be of interest to ~"group::ecosystem", possibly ~"group::portfolio management".