Skip to content

Create a GFM Reference for Alerts

Problem to be solved

Adding references prefixes for GitLab alerts allows users can more easily reference/share alerts in GitLab issues. It will also have the benefit of helping users to more quickly distinguish alerts in views like the to-do screen.

Intended users

Further details

This work supports the direction of the Alert Management product category.

Proposal

Add reference pref-fix to alerts so that users can mention them in markdown fields just like how issues and merge requests are handled. Current references are here.

All are capital characters in the top numbers row of a standard US keyboard. The ones that are left are ^ ( ) + -

We do not want to conflict with something people might naturally write. Many of the 'leftover characters' could be used in math. Repeated characters might be something to think about. alert !!22

The following discussion from !33743 (merged) should be addressed:

  • @splattael started a discussion: (+3 comments)

    Since alerts do have iid we could use it as reference but then alerts don't have any reference prefixes (e.g # for issues, ! for merge requests, @ for users, $ for snippets, & for epics).

    For fun, I've added iid.to_s and looked like:

    Screenshot_from_2020-06-04_21-56-40

    Not very impressive, so let's skip it 👍

    Should we mention this caveat in the method docs that we could use iid but don't have defined a reference prefix?

    @sarahwaldner Are we planning to add a reference prefix for alerts so users can mention a specific alert easier? Like #23 for issues etc. (see example above). I assume a "no" but still wanted to check.

Amelia Bauerly @ameliabauerly · 18 hours ago

My opinion: it might be nice to add an alert number at some point so users can more easily reference/share alerts. It will also have the benefit of helping users to more quickly distinguish alerts in views like the to-so screen.

When I look at the screenshot in the issue description, for example: if we had many different alerts, it would be hard for me to differentiate them visually, quickly, because they all just say alert. I know that the titles are different but, I don't really notice that until I look closely. With the issue version of the to-do, you can quickly see there are many different issues just through seeing the links: issue #6 (closed), issue #1 (closed), etc. Just having the different link names helps to more quickly understand the number of different alerts you have to-dos for.

For these reasons, it seems like it might be nice to add an alert number...at some point. Not necessarily immediately but, perhaps in future?

Not sure what Sarah thinks, though?

Allison Browne

If you look at the current references here:

https://docs.gitlab.com/ee/user/markdown.html#special-gitlab-references

All are capital characters in the top numbers row of a standard US keyboard. The ones that are left seem to be ^ ( ) + -

we probably don't want to conflict with something people might naturally write. I think many of the 'leftover characters' could be used in math. Repeated characters might be something to think about. alert !!22 (merged)

Permissions and Security

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?

Links / references

Release Notes

In GitLab 13.4, we improved GitLab alerts by adding a specific references prefix which makes it simple for you to share and reference alerts in any markdown field on incidents, issues, and merge requests. This reference prefix also helps to disseminate between to-dos from alerts and other items such as issues and merge requests!

https://docs.gitlab.com/ee/operations/incident_management/index.html

Edited by Sarah Waldner