Triage rules¶
Triage rules automate the decisions your team makes over and over. A rule watches for an event (a new signature, a regression, a root-cause run finishing), checks whether the signature is one it cares about, and then acts: sets a status, assigns an owner, classifies, labels, links a bug, notifies people, or starts a root-cause run. Every match is logged with what each action did. This page covers how rules work, then gives recipes you can copy.
Open Triage rules in the sidebar (or the Rules tab under settings, or Rules on the Triage page).
Anatomy of a rule¶
flowchart LR
T["When: triggers"] --> S["Which signatures: branches, saved search"]
S --> M["Conditions"]
M --> A["Then: actions in order"]
A --> P{"Stop processing?"}
| Part | Editor section | API field | Required |
|---|---|---|---|
| Name | Rule · Name | name (up to 128 characters) |
Yes |
| On or off | Enabled | enabled |
Default on |
| Triggers | When | triggers (1 to 6) |
Yes |
| Branch scope | Which signatures · Branches | scope_branches (up to 50) |
No |
| Saved-search scope | Which signatures · Within saved search | scope_saved_search_id |
No |
| Conditions | Which signatures · Conditions | match (a filter expression) |
No |
| Actions | Then | actions (1 to 10) |
Yes |
| Stop processing | Stop processing | stop_processing |
Default off |
A rule matches a signature when one of its triggers fired for it and the branch scope, the saved search and the conditions all hold. Leave the scope and conditions empty to match every signature the trigger fires for.
Triggers¶
| Editor label | API value | Fires when |
|---|---|---|
| A new signature appears | signature.new |
A signature is seen for the first time. |
| A signature is hit again | signature.hit |
A signature gets its first hit in a regression. It fires once per signature per regression, including the regression where the signature first appears. |
| A signature comes back after an absence | signature.recurred |
A signature is hit after a complete regression on the same branch ran without it. See Signatures for recurrence. |
| A resolved signature regresses | signature.regressed |
A resolved signature is hit by a regression that ran after it was resolved, and DV Forge moves it to Regressed. |
| A root-cause run finishes with a hypothesis | signature.agent_complete |
A root-cause run launched on the signature completes. Failed runs don't fire it. |
| A regression finishes | regression.complete |
A regression is marked complete. The rule looks at every signature the regression hit. |
A regression finishes waits until all of the regression's uploads have been processed, so the rule sees the whole regression. It checks again every few seconds; after about five minutes it runs on whatever has been processed.
When several triggers fire for the same signature in the same regression (for
example signature.new and signature.hit together), each rule still
evaluates that signature once.
Rules act on events that happen while they're enabled. They don't go back over history.
Scope¶
Branches. Enter branch names or globs, separated by commas or spaces:
main, release/*, feature-?. * matches any run of characters (including
/), ? matches one character, and matching is case-sensitive. The branch of
the regression that fired the trigger must match one of them. Leave it empty
for every branch.
Branch scope and root-cause runs
The A root-cause run finishes with a hypothesis trigger doesn't come from a regression, so it has no branch. A rule with a branch scope never matches it. Leave Branches empty on rules that use that trigger.
Within saved search. Pick a saved search shared with the project. Only shared searches can scope a rule, and their filter can't use "me". While a rule uses a search, the search can't be unshared or deleted; see Saved searches.
Conditions¶
Conditions uses the same builder and filter language
as the Triage page: rows of field, operator and value under Match all
or any. One difference: rules have no signed-in user, so Me isn't
available. If you start a rule from a filter that used Me, those
conditions are dropped and the editor tells you.
Conditions are evaluated as of the regression's start time, not the moment the
rule runs. A condition such as Last seen · in the last · 7d means
"within 7 days before this regression", so replaying the same uploads gives the
same result. For A root-cause run finishes with a hypothesis, which has no
regression, relative times count from when the rule runs, moments after the
run finishes.
Actions¶
Actions run in the order listed. An action that can't apply to a signature is skipped, the reason is logged, and the remaining actions still run.
| Editor label | API shape | Notes |
|---|---|---|
| Set status | {"type": "set_state", "state": "investigating"} |
Any status except Waived (needs a person's approval), Regressed (only DV Forge sets it) and Tracked (use Link bug, which records the bug). The lifecycle rules apply: a move that isn't allowed from the signature's current status is skipped. A rule can mute, but without an end time. |
| Assign | {"type": "assign", "user_id": "…"} |
The person must be a member of the project's organization. Like a manual assignment, they start watching and are notified. Skipped if already assigned to them. |
| Classify | {"type": "classify", "classification": "infra"} |
One of rtl, dv, infra, tool, unknown (shown as RTL, DV, Infra, Tool, Unclassified). Never overrides a classification a person set; that's skipped. |
| Add label | {"type": "label", "label_id": "…"} |
A label of this project. You can create one from the editor with New label. Skipped if the label was deleted later. |
| Link bug (tracks it) | {"type": "link_bug", "bug_ref": "REL-482"} |
Records the bug. An open signature moves to Tracked; others keep their status. |
| Notify | {"type": "notify", "to": ["assignee", "watchers", "…user id…"], "message": "…"} |
Up to 20 recipients: The assignee, Everyone watching, and named members. Optional message up to 1,000 characters. Only people still in the organization are notified; skipped if nobody is. |
| Run the root-cause agent | {"type": "run_agent"} |
Starts a root-cause run. Only a project_admin (or org_admin) can add it to a rule. At most 10 runs per rule in any 24 hours. Skipped while a run is already in flight on the signature, or when the signature has no scenario the agent can run. See Root-cause agent. |
Changes made by rules appear in the signature's timeline as made by Rule "name", exactly as if a person had made them, and send the same notifications.
Evaluation order and stop processing¶
Rules run top to bottom, in the order shown under Evaluation order. Each
rule is checked against all the signatures an event batch touched, and its
actions run on each match before the next rule is checked. A later rule sees
what earlier rules changed: if rule 1 labels a signature infra, rule 2's
condition Label · is · infra matches it.
Tick Stop processing on a rule to end the run for a signature when that rule matches it: rules below it don't run for that event. The rules list marks such rules stops.
Exactly once, and repeatable¶
- Each event is evaluated once. If a worker restarts mid-run, the rules aren't applied twice.
- Rules only see events whose change was saved. An upload that failed doesn't trigger anything.
- Within one run, signatures are processed in a stable order, and conditions use the regression's time. Replaying the same uploads produces the same matches and the same log.
Preview: "Would match N"¶
While you edit, the editor shows Would match N live signatures today, with a few examples. It counts live signatures (not merged, with hits) that the conditions and the saved search select right now, with relative times counted from now. With a branch scope, it counts signatures that have ever been seen on one of those branches.
The preview ignores triggers. It tells you how broad the conditions are, not how many signatures the rule will act on: the rule only acts when a trigger fires.
The run log¶
Every match is recorded:
- Recent runs on the rules page shows the latest 10. Full log opens the Rule run log, 50 per page, which you can narrow to one rule.
- A rule's own page lists its recent matches.
- Each signature's page shows the rules that matched it.
Each entry shows when, the rule, the signature, the trigger, and each action's outcome:
| Outcome | Meaning |
|---|---|
| applied | The action changed the signature (or notified someone, or started a run). |
| skipped | The action couldn't or didn't need to apply. Hover it for the reason, for example "already labeled", "already investigating", "no recipients", "a root-cause run is already in flight", or "daily cap of 10 runs reached". |
| failed | The rule's conditions or saved search no longer compile (for example the search was changed). Logged once per run. |
Executions of a deleted rule stay in the log under the rule's name, marked (deleted).
Create, edit and manage rules¶
Create a rule. Select New rule, fill in the sections, check the preview, and select Create rule. New rules go to the bottom of the order. You can also start from a bulk action on the Triage page with Make this a rule.
Edit a rule. Select its name, change it, and select Save rule.
Reorder. Use the up and down arrows in the rules list.
Enable or disable. Toggle Enabled in the list or in the editor. A disabled rule shows off and doesn't run.
Delete. Select Delete rule and confirm. It stops running at once; its past runs stay in the log.
Who can author rules¶
| Task | Role needed |
|---|---|
| See rules, previews and the run log | viewer |
| Create, edit, enable, disable, reorder or delete a rule | triager |
| Create, edit, enable, disable or delete a rule that runs the root-cause agent | project_admin |
Recipes¶
Each recipe shows the rule as JSON (the body of
POST /v1/triage-rules?project=org/project) and as the editor fields. Replace
the ids: get label ids from GET /v1/labels, member ids from GET /v1/members,
and saved-search ids from GET /v1/saved-searches.
License and infrastructure failures¶
Classify license and machine problems as infrastructure, label them, close them as not a bug, and keep later rules from assigning them to anyone.
- Name: Infra: license and disk failures
- When: A new signature appears
- Conditions: Match any of: Text · contains ·
license; Text · contains ·No space left on device; Text · contains ·Connection refused - Then: Classify · Infra; Add label · infra; Set status · Not a bug
- Stop processing: on
{
"name": "Infra: license and disk failures",
"triggers": ["signature.new"],
"match": {"any": [
{"field": "text", "op": "contains", "value": "license"},
{"field": "text", "op": "contains", "value": "No space left on device"},
{"field": "text", "op": "contains", "value": "Connection refused"}
]},
"actions": [
{"type": "classify", "classification": "infra"},
{"type": "label", "label_id": "<id of label infra>"},
{"type": "set_state", "state": "not_a_bug"}
],
"stop_processing": true
}
Put this rule first so routing rules below it never see these signatures.
Route a block's failures to its owner¶
Assign new signatures from one design block to the engineer who owns it, using the component recorded on the failing jobs.
- Name: DMA failures to Priya
- When: A new signature appears
- Conditions: Component · is ·
dma - Then: Assign · Priya; Add label · dma
The component comes from your uploads (for example a component property in
JUnit). See The dvforge CLI.
Put regressions back in someone's hands¶
When a fix doesn't hold, move the signature to Investigating and tell the verification lead, with a note. (DV Forge already alerts the assignee and watchers when a signature regresses; this reaches someone else and records a next step.)
- Name: Regressions back to investigating
- When: A resolved signature regresses
- Then: Set status · Investigating; Notify · The assignee, Sam,
message
Regressed after the fix. Please re-check the fix commit.
Confirm agent hypotheses automatically¶
If your team trusts the root-cause agent's hypotheses for a class of failure, confirm them without waiting for a person.
- Name: Auto-confirm RTL hypotheses
- When: A root-cause run finishes with a hypothesis
- Branches: leave empty
- Conditions: Classification · is · RTL
- Then: Set status · Root-caused; Notify · The assignee
Label things that keep coming back¶
Flag signatures that have come back three or more times so they get a closer look.
- Name: Flag recurring signatures
- When: A signature comes back after an absence
- Conditions: Recurrences · at least ·
3 - Then: Add label · recurring; Notify · Everyone watching
Link release-branch hits to the release bug¶
During a release, track every signature seen on the release branches against one release bug.
- Name: Release 2026.11 hits to REL-482
- When: A new signature appears; A signature is hit again
- Branches:
release/2026.11* - Conditions: Status · is none of · Resolved, Not a bug, Waived, Muted
- Then: Link bug ·
REL-482
{
"name": "Release 2026.11 hits to REL-482",
"triggers": ["signature.new", "signature.hit"],
"scope_branches": ["release/2026.11*"],
"match": {"all": [
{"field": "status", "op": "not_in",
"value": ["resolved", "not_a_bug", "waived", "muted"]}
]},
"actions": [{"type": "link_bug", "bug_ref": "REL-482"}]
}
Open signatures move to Tracked. Without the condition, closed and parked signatures would get the bug recorded too, keeping their status.
Start root-cause runs on new RTL failures¶
Have the agent look at every new RTL-classified signature on main as soon as
it appears. Saving this rule needs the project_admin role.
- Name: Root-cause new RTL failures on main
- When: A new signature appears
- Branches:
main - Conditions: Classification · is · RTL
- Then: Run the root-cause agent
The rule starts at most 10 runs in any 24 hours; further matches are logged as skipped. Pair it with the auto-confirm recipe above if you want hypotheses confirmed too.
Triage a nightly once it finishes¶
When a regression completes, assign anything still untriaged and unowned in a shared "Nightly blockers" search to the person on triage duty.
- Name: Nightly: unowned blockers to triage duty
- When: A regression finishes
- Branches:
main - Within saved search: Nightly blockers
- Conditions: Status · is · Untriaged; Assignee · is empty
- Then: Assign · Alex
{
"name": "Nightly: unowned blockers to triage duty",
"triggers": ["regression.complete"],
"scope_branches": ["main"],
"scope_saved_search_id": "<id of shared search Nightly blockers>",
"match": {"all": [
{"field": "status", "op": "eq", "value": "untriaged"},
{"field": "assignee", "op": "is_null"}
]},
"actions": [{"type": "assign", "user_id": "<Alex's user id>"}]
}
Rules through the API¶
| Request | What it does |
|---|---|
GET /v1/triage-rules |
The project's rules, in evaluation order. |
POST /v1/triage-rules |
Create a rule (body as in the recipes). |
GET / PATCH / DELETE /v1/triage-rules/{id} |
Read, change or delete one rule. PATCH takes any subset of the fields. |
POST /v1/triage-rules/reorder |
{"ids": [...]} listing every rule of the project once, in the new order. |
POST /v1/triage-rules/preview |
{"match", "scope_branches", "scope_saved_search_id"}; returns matched and up to 5 sample signatures. |
GET /v1/rule-executions |
The run log, newest first. Narrow with rule_id or signature_id; limit and offset page it. |