Issue Templates and Labels in GitLab: Structured Bug Reports and Quick Actions

1. The problem with unstructured bug reports

"Checkout is broken" is the most common form of a bug report and at the same time the least helpful. Without reproduction steps, without browser or environment information, and without stating expected versus actual behavior, the developer responsible often spends more time asking follow-up questions than actually debugging. These follow-up-question loops are one of the biggest but least visible time sinks in everyday development work, because they are spread out over days and rarely stand out as a single large time block.

GitLab solves this structurally with issue templates, which can be automatically loaded as a form template when creating a new issue, and a label system that consistently reflects category, priority, and status. Combined with quick actions that trigger status changes directly in the description text or a comment, this creates a workflow that raises the quality of the initial report without requiring reporters to learn a separate tool.

2. A bug report template with the right required fields

Issue templates are stored as markdown files in the .gitlab/issue_templates/ directory and then appear in the "Choose a template" dropdown when creating a new issue. A good bug report template does not force the reporter into unnecessary effort, but does ask for the information that is genuinely indispensable for reproduction: concrete steps, expected behavior, actual behavior, and relevant environment data such as browser, Magento version, or store view.

It matters to keep the template deliberately short. A form with twenty required fields leads reporters to ignore the template or fill fields with placeholder answers like "don't know", which defeats the original quality intent. Five to eight clearly worded sections with short example text in comment form (which gets overwritten while filling it out) deliver the best results in practice.

# .gitlab/issue_templates/Bug.md

## Summary
<!-- One sentence: what is broken? -->

## Steps to reproduce
1.
2.
3.

## Expected behavior
<!-- What should happen? -->

## Actual behavior
<!-- What happens instead? Attach screenshot/log. -->

## Environment
- Store view:
- Browser/version:
- Magento version: 2.4.8-p4
- Occurring since (date/deploy):

## Severity (reporter's assessment)
- [ ] Critical: purchase/checkout not possible
- [ ] High: core function impaired
- [ ] Medium: workaround available
- [ ] Low: cosmetic

/label ~bug ~needs-triage

3. A second template for feature requests

Bug reports and feature requests need different templates because they answer different questions. While a bug report aims at reproducibility, a feature request needs to clarify the business value, the affected audience, and possible alternatives before a technical assessment even makes sense. A second template under .gitlab/issue_templates/Feature.md with sections like "Problem", "Proposed solution", and "Affected user group" prevents feature requests from ending up as unstructured walls of text in the backlog.

Both templates can be configured as the default template for the entire project (Settings > General > Default description template for issues), though that is of limited use once there are multiple templates. It is more practical to make the selection dropdown clearly visible and briefly explain in the project README when each template should be used, so new team members don't have to guess.

4. A label hierarchy that actually scales

A common mistake is a label system that grows organically and, after a year, consists of fifty unstructured, partially overlapping labels where nobody knows anymore whether urgent or priority::high is the right one. GitLab supports scoped labels with colon notation, such as priority::high and priority::low, which mutually exclude each other: when a new priority label is set, GitLab automatically removes the previous one from the same category. This prevents contradictory states like priority::high and priority::low existing at the same time.

A proven structure consists of four to five categories: type:: for bug, feature, task; priority:: for urgency; status:: for the workflow state such as triage, in-progress, blocked; and team:: for the functional assignment. This scoped-label structure often replaces elaborate custom fields, which are not even available in GitLab CE, while staying understandable to new team members without training.

# Creating labels via the GitLab API (example type/priority/status)
curl --request POST --header "PRIVATE-TOKEN: <token>" \
  "https://gitlab.example.com/api/v4/projects/123/labels" \
  --data "name=type::bug&color=%23d9534f"

curl --request POST --header "PRIVATE-TOKEN: <token>" \
  "https://gitlab.example.com/api/v4/projects/123/labels" \
  --data "name=priority::high&color=%23f0ad4e"

curl --request POST --header "PRIVATE-TOKEN: <token>" \
  "https://gitlab.example.com/api/v4/projects/123/labels" \
  --data "name=status::triage&color=%235bc0de"

5. Quick actions: labels and assignments without switching forms

Quick actions are text commands that GitLab recognizes in a new issue description or a comment and translates into actions without the reporter having to leave the form. As shown in the bug template above, /label ~bug ~needs-triage automatically sets the right labels upon creation. Similarly, /assign @developer, /milestone %"Sprint 24", or /due 2026-08-20 can set additional metadata directly during creation, which is especially valuable for recurring ticket types such as support escalations.

An often-overlooked benefit of quick actions is their composability in comments after creation: during a triage pass, a team lead can prioritize, remove from the triage queue, and assign all at once with a single comment such as /label ~priority::high /remove_label ~needs-triage /assign @backend-team. Compared to using the sidebar, this saves several clicks per issue, which adds up noticeably during a daily triage of twenty to thirty new issues.

6. A triage process that consistently uses labels

Labels only unfold their value through a consistent process behind them. A daily or several-times-weekly triage session, where all newly arrived issues with the needs-triage label are worked through, has proven effective. During this session, every issue gets a type:: label, a priority:: label, and, if immediately recognizable, an assigned team, before the needs-triage label is removed.

This process prevents two common problems at once: first, issues do not silently sit in a queue, because the needs-triage label remains immediately visible in a filtered board. Second, it prevents priorities from being determined solely by the loudest reporter rather than a traceable assessment, because the triage decision remains visible in the label and can be reviewed afterward.

7. Issue boards as the visual consequence of the label system

A consistent label system pays off especially in issue boards, whose columns can be directly coupled to status:: labels. When a team member drags a card from "In Progress" to "Review", GitLab automatically changes the underlying scoped label without anyone having to switch to the issue details manually. This makes progress visible to the whole team at a glance, without needing to maintain additional tools like Jira or Trello in parallel.

For larger projects, it is also worth having a second board, filtered on type::bug and sorted by priority::, that serves exclusively as a working view for the support and QA team, while the development team uses its own board focused on sprint milestones. Since both boards are based on the same issues and labels, the underlying data stays consistent even though different roles see different slices of it.

8. Making response times per priority traceable

A label like priority::high is only more than a sticker if it is also tied to a clear expectation for response time. It has proven effective to define a documented target response time for every priority level, for example four hours for priority::high and two business days for priority::low, and to record that expectation in the project wiki or directly in the label description text. That way both reporters and assignees know what a given label actually means, instead of priority becoming a subjective assessment without consequence.

The actual response time per priority level can be evaluated via the GitLab API by comparing the timestamp of the label assignment with the timestamp of the first comment or the first status change. A monthly report on this metric objectively shows whether the self-imposed response times are being met, and makes it visible when a team is persistently overloaded, instead of that state only becoming apparent through unhappy customers or escalated tickets.

9. Common mistakes with templates and labels

The most common mistake is a label system that is too granular without a scoped-label structure, where priority, type, and status exist as equal, ungrouped labels side by side. Without colon notation, contradictory combinations like high-priority and low-priority on the same issue accumulate quickly, because GitLab cannot enforce mutual exclusivity without scoped labels.

A second common mistake is creating templates once and never maintaining them afterward, even though the product landscape or team structure has changed. A quarterly review of the templates, checking whether the requested fields still match the current system landscape, prevents a template with outdated store view names or environments that no longer exist from continuing to be used. The table below summarizes the key building blocks and their respective benefits.

10. Summary

11. FAQ: Issue Templates and Labels: The Essentials at a Glance