Skip to main content
Investigation rules decide which alerts and incidents Rootly AI SRE investigates automatically and which resource-specific instructions it applies to manual or automatic runs. Choose Alerts or Incidents in the rule’s Applies to selector. Incident conditions use severity, services, teams, or incident types. Rules can add instructions to manual incident investigations or start automatic ones. Scheduled maintenance incidents are excluded.

​
Create a Rule

Configure a rule and preview it against your recent alerts or incidents before saving.
Paths on this page use the consolidated AI SRE navigation, which is rolling out. If your sidebar still shows AI & Agents, open rules under AI & Agents → AI SRE → Investigation rules. See Where AI Settings Live.
1

Open Investigation Rules

With an Incident Response seat, open AI SRE → Atlas → Investigation rules. An eligible admin without that seat can open the direct rules surface by appending /account/ai/surfaces/investigation_rules to the Rootly app URL.
2

Create the Rule

Select New rule, choose Alerts or Incidents, then enter a name that identifies the class, such as Critical checkout alerts.
3

Add Conditions

Select the fields, operators, and values the rule should match. All conditions must match. Leave the condition list empty to match every resource of the selected type.
4

Review Matches

Use the per-condition and combined counts to check the last 90 days. Open the matching-resource list to inspect the alerts or incidents behind a count.
5

Add Rule Instructions

Optionally add guidance for this alert or incident class, such as the service-specific signal or deploy source AI SRE should check.
6

Choose the Run Mode

Select Manual, Auto-run, or Paused. New rules start in Manual. Optionally set a cooldown to limit how often this rule can start automatic investigations, then select Save.
Incident Response Owners and Admins, and On-Call Admins, can create and manage investigation rules after your Rootly account team enables AI SRE for the current team. This rule surface does not require an Incident Response seat, but admins without that seat must use the direct path above because the broader AI & Agents configuration area remains seat-gated. Other members with an Incident Response seat can view the rules list but can’t create, edit, delete, or preview rules. See Manage User Permissions for the canonical matrix. AI SRE is enabled separately from the Opt in to Rootly AI capabilities setting, so contact your Rootly account team to turn it off. Manage rules in the Rootly web app or through the beta Investigation Rules API.

​
Rule Settings

​
string
required
A recognizable label for the alert or incident class. Use a name that distinguishes the rule from other rules in the list.
​
Fields and values that must all match. Values within one condition match any selected value. An empty condition list applies the rule to every resource of its selected type.
​
string
Guidance added to investigations of matching alerts or incidents, including manual runs. Rule instructions are added alongside your Global and AI SRE instructions rather than replacing them. Instructions guide the investigation but don’t count as evidence.
​
required
Controls whether matching alerts or incidents run automatically, wait for a manual start, or ignore this rule.
​
integer
After this rule starts an automatic investigation, prevent the same rule from starting another until the cooldown expires. If the investigation fails to start, the cooldown is released. Leave it blank or enter 0 to disable the cooldown. The value must be a whole number from 0 through 2147483647. Editing other rule settings doesn’t reset a cooldown that’s already running. Setting the cooldown to 0 or clearing it ends any running cooldown at once. Changing it to another positive value doesn’t shorten or extend one that’s already running.

​
Condition Fields

Alert rules use the fields below. Incident rules instead use severity, services, teams, and incident types. Title, description, and custom-field conditions support these operators:
  • is one of matches when the whole value equals a selected value, without case sensitivity.
  • contains one of matches when the field contains a selected value without case sensitivity.
  • is not one of excludes the selected exact values.
Urgency, source, status, and group status support is one of and is not one of. With is not one of, an alert with no value in the field doesn’t match a title, description, urgency, source, or status condition. A custom-field condition does match an alert that has no value for that field. A rule that already has a payload condition, which matches a value at a payload path such as details.region, shows that path in the editor. The field picker doesn’t offer payload conditions for new rows, and the 90-day counts leave them out. An alert without the payload path never matches a payload condition, even with is not one of.
Start with stable fields such as urgency, source, and a service custom field. Use contains one of on the title or description when the alert text is the only reliable signal.

​
Run Modes

Manual investigations include runs started from the alert’s or incident’s AI SRE tab, from Slack, and with Rerun investigation where it’s available. Rootly checks Auto-run rules once for an alert or incident, shortly after creation, against the resource as it is at that point. Rules you create or edit later don’t reach existing resources, and later changes don’t start another check. If an investigation already exists for the resource, another matching trigger doesn’t start a duplicate run. Scheduled maintenance and Example incidents (kind: example) are excluded from automatic starts, and an investigation on a linked alert can suppress an incident’s run. Incident creation with notifications disabled also skips automatic starts. A positive cooldown suppresses automatic starts for other resources matched by that rule until the rule’s cooldown expires. Matches during a cooldown are skipped rather than queued. Manual investigations remain available. Example incidents are distinct from Test Incidents (test or test_sub). Test kinds aren’t excluded by the Example-incident check.

​
Account-Level Automatic Investigation

Your Rootly account team can also turn on automatic investigation for the selected team. It may not be enabled for your team, and there’s no setting for it in AI & Agents. When it’s on, it changes what the run modes do:
  • An eligible alert or incident that matches no Auto-run rule is still investigated automatically, without rule instructions.
  • An eligible alert or incident that matches only a Manual or Paused rule is still investigated automatically, without that rule’s instructions.
  • While the matching Auto-run rule’s cooldown is active, the resource isn’t investigated automatically. It doesn’t fall through to a later rule or to account-level automatic investigation.
See Running an Investigation for how account-level automatic investigation also covers incidents.
An automatic run has no initiating responder. It uses the Rootly AI SRE background identity, the team’s configured connector credentials and any tool allowlists, and, when enabled, registered Private Agent capabilities authorized for the ai-sre system actor. This is not a read-only guarantee. Built-in connector tools can accept provider-defined commands or queries that change data when provider-side controls allow it. Atlassian, Notion, Linear, Braintrust, Honeycomb, AWS, and the Cloudflare connectors pass through the provider’s full tool catalog, so the scopes and roles you grant in the provider set the boundary. Custom MCP and Private Agent can also expose write-capable operations.For Auto-run rules, and whenever account-level automatic investigation is on, allow only built-in connector capabilities and provider commands, Custom MCP tools, Private Agent capabilities and local policies, and provider credentials that are safe for unattended use without an interactive approval pause.

​
How Overlapping Rules Behave

More than one rule can match the same alert or incident. Only one rule applies to a run, and AI SRE doesn’t merge instructions from other matching rules. AI SRE handles the overlap in two parts:
  • Starting the run: the matching Auto-run rule with the lowest position controls the automatic start and its cooldown.
  • Applying instructions: for a run someone starts, the matching non-paused rule (Manual or Auto-run) with the lowest position contributes its rule instructions. For an automatic run, the Auto-run rule that started it contributes them, even when a higher-priority Manual rule also matches.
Rootly appends rules created in the web app to the bottom of the stored priority list. Unless positions have changed through the API, the oldest remaining rule has the lowest position and wins when multiple rules match. The rules table lists the newest rules first by default. Editing a rule in the web app or sorting the table doesn’t change its priority. The web app has no reorder control; use the beta API’s writable position attribute to change priority. Because manual runs also consider Manual rules, a manual run can use a different rule’s instructions than the automatic run on the same alert or incident. Create mutually exclusive conditions when overlapping rules would give different guidance, or keep their instructions compatible. Don’t use the table’s current sort order to resolve an overlap.
An empty-condition Auto-run rule matches every resource of its selected type. Check the 90-day preview before saving it to avoid starting investigations for noisy or low-value alerts or incidents.

​
Design Reliable Rules

  • Start in Manual mode and compare the preview with the alert or incident class you intended to match.
  • Use Auto-run for alerts or incidents with a clear owner and enough connected evidence to investigate.
  • Add a cooldown when a noisy alert or incident class can create many distinct records in a short period. A cooldown is shared by every resource matched by that rule.
  • Keep rule instructions scoped to the matched alert or incident class. Put shared guidance in AI SRE instructions.
  • Prefer stable normalized fields over free-form title text when both are available.
  • Pause a rule while changing an alert source or payload contract.
  • Review the Matches (7d) column in the rule list for unexpected growth or inactivity. It counts investigation-rule usage for both alert and incident rules in the last seven days, including manual runs and reruns, so one resource can count more than once.

​
Troubleshooting

Open the rule and inspect the 90-day count for each condition and for all conditions together. For alert rules, add a stable discriminator such as source, urgency, or a service custom field. For incident rules, consider severity, services, teams, or incident types. Values inside one condition use any-match behavior; separate conditions use all-match behavior.
Confirm the rule is in Auto-run mode and that the alert or incident matches every condition. Check the condition values against the Matching alerts or Matching incidents preview for the selected resource type, whether a higher-priority matching Auto-run rule is selected, and whether that rule’s cooldown is still active. A resource that already has an investigation isn’t investigated again automatically. Rootly checks rules only once, shortly after creation, so a rule saved after the resource arrived doesn’t apply to it. For incidents, check the exclusions above and whether a linked alert already has an investigation. AI SRE also needs to be enabled for the current team.
Account-level automatic investigation is on for the selected team. Manual and Paused rules don’t stop it, and those runs don’t use rule instructions. Contact your Rootly account team to change it.
Another non-paused rule with a lower position may also match the alert or incident. The rules table’s sort order doesn’t change priority; use the beta API’s position attribute to reorder rules. Make rules with different instructions mutually exclusive, or pause the broader rule while you refine its conditions.

​
Frequently Asked Questions

Yes. For a run someone starts, the matching non-paused rule with the lowest position contributes its instructions, whether it’s in Manual or Auto-run mode. Automatic runs use the instructions of the Auto-run rule that started them.
Yes. Choose Incidents under Applies to and use Auto-run mode. AI SRE must be enabled, but account-level automatic investigation isn’t required. Scheduled maintenance and Example incidents (kind: example) are excluded. Creation with notifications disabled also skips automatic starts. An existing investigation on a linked alert can suppress the automatic incident run.
It matches every resource of its selected type. Priority follows stored position, not how specific a rule is. In Manual mode its instructions apply to manual runs unless a non-paused rule with a lower position matches. In Auto-run mode it can start investigations for eligible new alerts or incidents of that type, subject to cooldowns and existing investigations. A matching Auto-run rule with a lower position takes precedence. Keep specific rules ahead of a catch-all rule.
No. AI SRE uses the matching rule’s instructions together with your Global and AI SRE instructions. Rule instructions apply even when the Instructions feature isn’t enabled for the selected team.
Yes. Use the beta Investigation Rules API to create, read, update, and delete rules.

Rootly AI SRE

How AI SRE investigates, the outcomes it reports, and its settings.

Running an Investigation

Every way an investigation starts, including automatic runs.

Instructions

Team-wide guidance AI SRE follows in every investigation.

Evidence Sources

What an investigation can read, and the access boundaries automatic runs use.

Atlas

The context layer AI SRE and Rootly AI draw on, and where each part lives.