MVC: Expand Jira integration to allow viewing issues
Problem to solve
Customers have requested a "two-way data sync" with Jira during a large number of customer calls. In fact, many customers have directly implemented various approaches to this directly by leveraging the APIs of the two products and creating middleware. The primary driver of this is to allow developers to work in GitLab without having to leave to manage their tasks in Jira.
Being able to work in a single tool all day without having to leave is a straightforward request, and makes a lot of sense for those users. Many developers have little, if any, interaction with many of the other features that Jira offers. To those users who are simply working issues, having to leave your tool-of-choice to go view information that is highly-relevant to the work you're doing seems like a waste of time. For them, it's much simpler to be able to have everything they need in one place.
The persona this targets is a version of Sasha (Software Developer), but one whose company has invested in the Atlassian suite. Their work is being tracked by other personas (PdMs, PjMs, Designers, etc) in Jira, but they wish to work in GitLab full-time.
Note: future iterations may expand beyond this persona, but this MVC is tightly focused on serving this particular usecase.
User experience goal
The ultimate goal of this project is to allow a user to view and work with the Jira issues needed to get their job done, without having to leave GitLab.
However, in the scope of this MVC, the goal is to create an interface that allows a user to view a list of Jira issues in their GitLab project.
For this MVC, we should address the following user stories:
- As a developer using GitLab and Jira, I want to see a list of issues from my Jira project in GitLab, so that I don't have to leave GitLab (where I'm doing the majority of my work.
- As this developer, I want to be able to filter (_e.g. by assignee or creation date) and search that list of issues from GitLab, to narrow these results to what is most relevant to me.
- When I find an issue I'm interested in, I want it to be a link that takes me directly to that issue in Jira, so that I can spend less time navigating to the thing I need to learn more about.
To achieve this goal, we'll extend the current integration with Jira to address these specific uses. We'll add a view that lists the issues (allowing you to filter them and search). In a follow-up iteration, we'll add the ability for a user to click on an individual issue to see the details of it -- just like they would normally.
This MVC is limited to this functionality, but possible next iteration steps are listed below.
Issue list view
This view is based on the current issue list component that we use. This is the same view that our users see for other issue lists, with some additions:
- An indicator that these issues are being synced from Jira
- A link to view this list on Jira directly
- Each issue uses the Jira issue IDs, and indicates the difference with the Jira icon in its listing.
Leveraging our work on the Jira Importer, we have a foundation set for creating a translation layer that can take Jira issues and turn them in to GitLab issues.
We can use that layer to pull data from Jira, transform it in to GitLab issues, and interact with them normally from there. This gives us two huge advantages:
- We don't have to write a bunch of new code to support new, custom data structures
- The risk that we'll create an ongoing source of technical debt is lowered
This data flow will look something like:
Permissions and Security
Today, our integration leverages a single Jira user credentials to access all integration data. Typically, we recommend that a GitLab-specific Jira user be created to simplify future user administration tasks (i.e. deleting a user). This creates a possible complication, as the Jira permissions model may have specific restrictions around what data a user can view, and based on this configuration, we may display data outside that scope.
We should only allow
read actions for now, since any other actions would be taken by that single set of credentials, and at this time we have no ability to federate individual users.
This functionality should be documented on the GitLab Jira Integration page.
Possible next iteration steps
This MVC is strictly read-only. This is because our current integration relies on a single set of (typically) administrator-level credentials, so the risk of allowing other creative/destructive actions is high.
With that in mind, the next steps for iterating probably look something like:
- Add the ability for individual users to federate their Atlassian account
- Add a detail view that allows for basic interactions with the issue, like commenting and changing it's status (e.g. "To Do" -> "Doing" -> "Done"), or adding labels
- Add a kanban or sprint "board" view that allows users to see a closer approximation of their normal Jira experience.
And further down the line:
- Consider making the user/password optional fields on the main Jira Integration (relying on individual federated accounts)
- Support filtering/searching via JQL (potentially complex, based on current concept for architecture)
Other valuable co-related work
- Complete the mass-integration work at the group and instance level
- Improve transition ID configuration
- Add support for SMAL/oAuth
- Expanding our Jira Connect App to support self-hosted customers (not currently possible, would require API additions to Jira Server)
- (Pending this) adding build/pipeline data to our Jira Connect App
- (Pending this) add environment data to our Jira Connect App
- Support creating Jira issues from errored CI Logs when integrated
- Explore integrating Jira data in to our VSM tools
Concerns and Open Questions:
- Since we don't have a way to correlate users in Jira activity and GitLab users, how do we handle displaying comment/assignee/activity data?
- Would it be sufficient to hide that activity data in this view? From our perspective, a ton of value is in the comments, so probably not.
- Outlined above in Permissions and Security, how big of a concern is showing this data based on a (possibly) admin-level credential? Is that sufficient for an MVC? Do we need to support individual user federation first?
- Especially from the MVC perspective, a few approaches. We could have a toggle that enables/disables this functionality at the project-integration level, allowing it to be turned off where inappropriate. Additionally, we can explicitly call out how this works on that page reducing the likelihood that it's used inappropriately (but not solving for that completely).
- Particularly at this juncture, when these items are read-only, we'll need to be extra-cognizant of places where users can be confused by the functionality available on these issues. Ensuring that there is a clear visual indication of what is coming from where and why is key.
- We should work closely with UX on both the GitLab and Atlassian sides to create a playbook for how we want to approach this class of problems.
- Would it be possible to use the native
Issuesview, and incorporate these (imported from Jira) issues there?
- How much confusion would this create for users, and are there ways to mitigate that appropriately? We'd need to do specific UX research and validate concepts with users before going down this path.
- Is it possible support JQL-based queries in the search/filter component?
- JQL is a powerful tool, and heavily used by some, but unclear if it's relevant for this persona.
- Can/should we retain the state of filters over time?
- Should we investigate merging this view in to the main Issues view, using a visual indicator to allow users to consume either tool directly?
- This requires specific UX research, noted below.
- Can we support creating a MR from GitLab that is linked to a Jira issue immediately?