docs / labels & decorations
Labels & decorations
Thirteen labels, three built-in decorations, and five precedence rules determine how a comment is interpreted — including whether it blocks a merge. This page is the reference for all of them.
The grammar
Every validated comment starts with a prefix line. Anything after the first blank line is discussion. It is left entirely untouched by the parser.
label [decorations]: subject [discussion]
Casing errors are corrected rather than rejected. For example, Issue: raises W-CASE, a warning with an automatic fix.
The thirteen labels
Ten labels are enabled by default. Three more — typo, polish, and quibble — are available but disabled initially. They provide more specific alternatives to todo, suggestion, and nitpick, and repositories can enable them when useful.
| Label | What it means | Blocking | Shortcut |
|---|---|---|---|
| 🎉 praise | Highlights something done well. | Depends on decoration | ?pr |
| 🔍 nitpick | A minor preference with nothing significant at stake. | Never | ?ni |
| 💡 suggestion | A reasoned proposal for improving something. | Depends on decoration | ?su |
| 🔨 issue | Identifies a problem. Ideally accompanied by a suggestion. | By default | ?i · ?ib |
| 📌 todo | A small but necessary change. | By default | ?to |
| ❓ question | Asks for clarification about something uncertain. | Depends on decoration | ?que |
| 💭 thought | An idea that came up during the review, with no action requested. | Never | ?th |
| 🧹 chore | A side task that should be completed before acceptance. | By default | ?ch |
| 📝 note | Information worth calling out. | Never | ?no |
| 🏁 decision | Records the choice not to address a point and explains why. | Never | ?de |
| 🔤 typo | A typing mistake. | Disabled by default | ?ty |
| ✨ polish | A finishing improvement. | Disabled by default | ?po |
| 🪶 quibble | A debatable detail. | Disabled by default | ?qui |
Colours and icons are deliberately cosmetic. They are excluded from the enterprise floor. Changing them can never change a verdict or be locked down by an administrator.
decision — the label added by this toolkit
decision is not part of the original Conventional Comments specification. The toolkit adds it because enforce needs a controlled way to resolve exceptional situations. Without one, a blocking thread could remain unresolved indefinitely simply because its author is unavailable.
The one label detected in an otherwise unvalidated reply
Thread replies are not validated by default (validateReplies: false). A reply whose resolved label is decision is still recognized. Otherwise, this mechanism would only work in repositories that had independently enabled validation for replies.
E-DECISION-SUBJECT is an error, not a warning
A decision reply must meet minDecisionSubjectLength, which defaults to 20 characters. That is the only subject-length threshold applied to decision. Resolving a blocking thread therefore requires an actual explanation. wontfix is not enough.
decision: out of scope for this PR, debt tracked in PROJ-142 Agreed with the platform team on 3 Sep: the cache rewrite lands in Q4 and this handler is deleted with it.
Not everyone is allowed to record a decision. resolverOverrideGroup identifies the group whose members may override a resolution. Configuring that group is a prerequisite for enforce; leaving it empty disables both override mechanisms.
Decorations
Decorations qualify the meaning of a label. Three built-in decorations affect the blocking verdict. Custom decorations are also allowed by default: they can carry useful meaning for people without influencing whether the comment blocks.
| Decoration | Effect | Meaning |
|---|---|---|
| blocking | Blocking | Must be resolved before the subject under review can be accepted. |
| non-blocking | Non-blocking | Must not prevent acceptance. |
| if-minor | Non-blocking | Address it only if the required change turns out to be trivial. The author decides. |
| security test ux | None | Custom decorations. They can be displayed, counted, and indexed, but never affect the verdict. Organizations can define their own. |
An undecorated suggestion or question raises W-MISSING-DECORATION. Those are the two labels for which a reader genuinely cannot infer the blocking intent from the label alone.
Precedence — how blocking is determined
Five rules are evaluated in order. The first matching rule determines the result. There are no additional heuristics or hidden inputs.
| # | Condition | Result | Diagnostic |
|---|---|---|---|
| 1 | The label is alwaysNonBlocking, but a decoration forces blocking. | Use the label's own default. | E-CONFLICT |
| 2 | One decoration forces blocking while another forces non-blocking. | Use the label's own default. | E-CONFLICT |
| 3 | A decoration forces blocking. | Blocking | — |
| 4 | A decoration forces non-blocking. | Non-blocking | — |
| 5 | No decoration forces either result. | Use the label's blockingByDefault value. | — |
Rules 1 and 2 report an error, but they still produce a result. When a comment contradicts itself, the label's default is used as a deterministic fallback. Leaving the blocking state undefined would be worse: the system would be unable to determine whether the thread prevents acceptance, potentially leaving the pull request blocked with no actionable way to resolve the ambiguity.
Diagnostics
There are fifteen diagnostic codes. Errors make a comment non-compliant. They only affect merge eligibility when the repository configures formatSeverity: "error". Warnings are reported and counted but never cause a failure by themselves. Every diagnostic can be assigned a different severity — or disabled entirely — per repository through severities.
| Diagnostic | Raised when |
|---|---|
| E-NO-LABEL | The comment has no prefix line. |
| E-MALFORMED-PREFIX | The prefix resembles valid syntax but cannot be parsed. |
| E-UNKNOWN-LABEL | The label is not enabled for this repository. |
| E-EMPTY-SUBJECT | A label and colon are present, but the subject is empty. |
| E-DECORATION-SYNTAX | Decoration parentheses or separators are malformed. |
| E-UNKNOWN-DECORATION | The decoration is unknown and custom decorations are disabled. |
| E-CONFLICT | Blocking precedence rule 1 or 2 applies. |
| E-DECISION-SUBJECT | A decision does not provide a sufficient explanation. |
| Diagnostic | Raised when |
|---|---|
| W-CASE | The label uses the wrong casing. Includes an automatic fix. |
| W-DECORATION-STYLE | Decoration spacing or ordering is inconsistent. Includes an automatic fix. |
| W-SUBJECT-TOO-SHORT | The subject contains fewer than 5 characters. |
| W-SUBJECT-TOO-LONG | The subject exceeds 120 characters. |
| W-MISSING-DECORATION | A suggestion or question has no decoration. |
| W-NO-DISCUSSION | A blocking comment contains no discussion. |
| W-NOT-BLOCKABLE | A comment is marked as blocking in a context that cannot carry blocking state. |
A short subject is deliberately only a warning.
The threshold is five characters, and falling below it never produces an error. A short subject is not serious enough to justify blocking a workflow. Making minor issues punitive encourages people to work around the convention instead of using it. Enforcement works better when it reserves hard failures for things that genuinely matter.