VSA: Support Jira issues
Problem to solve
Customers that are using Jira for issue management want a way to view issue duration close-open) into VSA. They also want to see issue work breakdown based on their Jira Labels (some directly related to SAFE labels that we should support by default)
Proposal
There are 3 use cases:
- VSA Stages based on Jira event.
- Tasks by type breakdown based on Jira Labels. (out of scope for this issue)
- DORA metrics integration based on Jira/SNOW incidents. (out of scope for this issue)
Proposal based on the Spike Research:
- Assumption
- Customers write their custom stage events to GitLab and filter & retrieve it later on. It's on customers shoulders to decide WHEN exactly particular event happened outside of GitLab and safely deliver it to GitLab via API with all required data.
- Default stages and their implementation with external issues store.
Option A for VSA Stages based on Jira event workflow:
Before we start: client must have Maintainer+ access level API token.
- Client creates custom "external" stage with unique start & end event identifiers (e.g. "issue_created" and "issue_closed")
- When stage end event happens customer sends following mutation request to GitLab GraphQL:
addExternalValueStreamAnalyticsEvent(input: inputParams)
with following inputParams
param | Type | Required? | Description |
---|---|---|---|
groupPath | ID | full path of group where you want to see this VSA event | |
externalId | String | string containing global unique ID of Jira issue | |
startEventId | String | String from stage configuration. (e.g. "issue_created") | |
endEventId | String | String from stage configuration. (e.g. "issue_closed") | |
startEventTimestamp | Timestamp | Timestamp with timezone when start event happened | |
endEventTimestamp | Timestamp | Timestamp with timezone when end event happened | |
labels | Array of strings | Issue labels for filtering. Missing labels will be created at GitLab if not found | |
authorUsername | String | Issue author username. Group member with such username must exist at GitLab | |
assigneeUsernames | Array of Strings | Issue assignees usernames. Group members with such username must exist at GitLab | |
milestone | String | ID of associated milestone. Milestone must exist at GitLab | |
externalUrl | String | ? | String containing URL to Jira issue |
If response is successful then everything is OK and VSA will be refreshed soon to reflect new data.
Option B for VSA Stages based on Jira event workflow:
Click to expand
Cons: more complex to implement, more data to store. Pros: easier to use for clients, might be useful structure for further decoupling of VSA.
Before we start: client must have Maintainer+ access level API token.
- Client creates custom "external" stage with unique start & end event identifiers (e.g. "issue_created" and "issue_closed")
- When stage event happens customer sends following mutation request to GitLab GraphQL:
addExternalValueStreamAnalyticsStreamEvent(input: inputParams)
with following inputParams
param | Type | Required? | Description |
---|---|---|---|
groupPath | ID | full path of group where you want to see this VSA event | |
externalId | String | string containing global unique ID of Jira issue | |
eventId | String | Unique event ID e.g. "issue_created" or "issue_closed" | |
eventTimestamp | Timestamp | Timestamp with timezone when the event happened | |
labels | Array of strings | Issue labels for filtering. Missing labels will be created at GitLab if not found | |
authorUsername | String | Issue author username. Group member with such username must exist at GitLab | |
assigneeUsernames | Array of Strings | Issue assignees usernames. Group members with such username must exist at GitLab | |
milestone | String | ID of associated milestone. Milestone must exist at GitLab | |
externalUrl | String | ? | String containing URL to Jira issue |
If response is successful then everything is OK. VSA will refresh data for all stages where end event and start event data is already present.
Is this a cross-stage feature?
yes devopsplan ~"group::integrations" /cc @mushakov
What does success look like, and how can we measure that?
Number of users using Jira integration and accessing VSA
Related links
- Deep dive session: VSA - Support Jira issues
- How to implement Jira support
- Related comment: "VSA used to have an issue-focused perspective... it was refactored about 2 years ago to have a second focus on MRs, for the sake of organizations that use JIRA for their issues."
- Recent enhancement: Alternative start event to accommodate Jira issue users
This page may contain information related to upcoming products, features and functionality. It is important to note that the information presented is for informational purposes only, so please do not rely on the information for purchasing or planning purposes. Just like with all projects, the items mentioned on the page are subject to change or delay, and the development, release, and timing of any products, features, or functionality remain at the sole discretion of GitLab Inc.