Skip to content

Update Jira Comment Design

Problem to solve

There are multiple issues around customizing or changing the comments that the GitLab Jira integration produces:

  1. #21919 (closed)
  2. #17071 (closed)
  3. #29864 (closed)
  4. #35544 (closed)

All four of these issues may be able to be solved with a single, more elegant solution. Some propose customization and some propose changes, which leads me to believe there's definitely a problem here, and the right solution has yet to be found.

the comment section into our JIRA look a bit cluttered and we wanted to simplify it

Would be beneficial to include branch name so it can be easily figured out what branch it's applied to

users can change it for their specific needs. For example by including whole commit message and not just a commit title.

we hope to be able to include "repo name" and "target branch" in the Merge Request Link Message

Here's an example from @arturoherrero that shows the current state of this comment:

Example comment

Intended users

Gitlab/Jira users who are seeing these comments in the Jira application.

Further details

Proposal

After reading through all 4 of the related issues, it sounds like the root of the problems stem from either the lack of information or too much information being presented in the JIRA comments.

It looks like we already addressed the issue of showing too much information by making the comments optional in this MR.

I think that the most effective solution here would be to simply:

  1. Update the default comment template to include the branch name as mentioned in Issue 17071
  2. Include an option that shows all information in the comment. (e.g. SHA, IDs, entire commit message)

My assumption is that by doing both updates 1 and 2 should satisfy the needs of the majority. Moving forward, we would like to validate the need for allowing a fully customizable comment template message. For now, in order to make progress, I think making updates 1 and 2 for now is a good start.

UI update:

JIRA-comments-settings-v08

👉 Clickable prototype

UI Copy:

When a Jira issue is mentioned in a commit or merge request a remote link and comment (if enabled) will be created.

Standard

Includes username, project name, commit title and branch

All details

Includes Standard plus entire commit message, commit hash, and merge request

Comment types examples:

- Standard All details
Commit John Smith mentioned this issue in a commit of gitlab/help-docs on branch staging:

'This is an entire, very long commit message describing...'
John Smith mentioned this issue in a commit 0a97e017 of gitlab/help-docs on branch staging:

'This is an entire, very long commit message describing what is being updated and the reasons for why it is being updated.'
Merge request John Smith mentioned this issue in a merge request on gitlab/help-docs on branch staging:

'This is an entire, very long commit message describing...'
John Smith mentioned this issue in merge request !92203136 of gitlab/help-docs on branch staging:

'This is an entire, very long commit message describing what is being updated and the reasons for why it is being updated.'

Permissions and Security

Documentation

We will need to upgrade our Jira integration documentation with updated screenshots here: https://docs.gitlab.com/ee/user/project/integrations/jira.html

Links / references

/cc @lvanc

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.

Edited by 🤖 GitLab Bot 🤖