ROB-669: Add Platform docs for Alert Triage, Incident Grouping and Triggered Workflows

[ezra-robusta]

Linear: ROB-669

What changed

Adds a new Platform docs section covering the AI features that run in the Robusta Platform. None of these had any documentation before.

Page	Covers
platform/triggered-workflows.rst	The /webhooks endpoint and every query parameter, incl. cluster=xyz; creating a workflow; filter semantics; delivery-via-prompt; the daily limit; every outcome shown in the Events table
platform/alert-triage.rst	The triage pipeline, the account settings that gate it, agent/fallback resolution, statuses and skip reasons
platform/incident-grouping.rst	AI grouping by root cause, episodes, and the opt-in auto-attach matchers
platform/index.rst	Section overview with cards

Why

This came from a Slack thread: users had no way to discover the cluster=xyz trick for triggered workflows. It was already documented for alert webhooks on the Send Events API page, but Triggered Workflows had no page at all, so there was nowhere for it to live. The issue also asked for alert grouping to be documented as AI-based.

On "alert grouping is AI-based, replacing Runner-based grouping"

The issue framed the new AI grouping as replacing the older Runner-based grouping. Checking the code, that isn't quite the situation, so the docs say something slightly different:

• Incident grouping (new, AI) groups problems by root cause into persistent INC-### incidents. Platform-side.
• Notification grouping (grouping: on the Slack sink) threads messages to keep a channel quiet. Runner-side, in-memory, still fully supported, and not superseded.

The two are independent and can be used together, so rather than deprecating the old page I scoped it with a note and added a comparison table on the new page. Worth a sanity check from someone who knows the history — if the intent really is to retire the Slack-sink grouping, the framing should change.

There is a third thing users will meet: the duplicate collapsing in the alerts list. That one is AI-based too (it's step 1 of each investigation), so the new page says so rather than calling it legacy name-matching.

Cross-links added

Landing page, architecture, oss-vs-saas, the HTTP APIs index, send-events-api (both directions for the cluster param), and notification-grouping.

How it was verified

• Every factual claim was checked against the relay and frontend source — endpoint behavior, status codes, defaults, setting names, enum values, and UI navigation labels — and each finding was independently re-verified before being applied. That pass corrected a fair amount of the first draft, including menu paths (Settings, not "Pipeline Settings", is the button), a runs table that is dead code and never renders, the daily cap not applying to matcher attaches, and the skipped reason for unknown-cluster alerts.
• RST structure validated with docutils. I could not run a full Sphinx build — it needs graphviz, pandoc, and poetry install --extras=all (the extension imports the Robusta runtime), which isn't available in my environment. Worth confirming the CI docs build is green before merging; the risk is limited to directive/reference resolution.
• Icon names in the new grid cards are restricted to octicons already used elsewhere in the docs, since I couldn't verify unknown ones resolve.

Not in this PR

Natan's follow-up was really about the UI: the cluster=xyz option should be surfaced on the Triggered Workflows webhook-setup screen (WebhookSetupColumn.vue / SendEventsModal.vue), which today builds the URL without it. That's a robusta-frontend change and needs its own issue.

🤖 Generated with Claude Code

https://claude.ai/code/session_0118RAeFXTFoLcjyziH4tuSd

---

Generated by Claude Code

[github-actions]

✅ Docker image ready for 2900d85 (built in 39s)

• us-central1-docker.pkg.dev/robusta-development/temporary-builds/robusta-runner:2900d85

⚠️ Warning: does not support ARM (ARM images are built on release only - not on every PR)

Use this tag to pull the image for testing.

📋 Copy commands

⚠️ Temporary images are deleted after 30 days. Copy to a permanent registry before using them:

gcloud auth configure-docker us-central1-docker.pkg.dev
docker pull us-central1-docker.pkg.dev/robusta-development/temporary-builds/robusta-runner:2900d85
docker tag us-central1-docker.pkg.dev/robusta-development/temporary-builds/robusta-runner:2900d85 me-west1-docker.pkg.dev/robusta-development/development/robusta-runner-dev:2900d85
docker push me-west1-docker.pkg.dev/robusta-development/development/robusta-runner-dev:2900d85

Patch Helm values in one line:

helm upgrade --install robusta robusta/robusta \
  --reuse-values \
  --set runner.image=me-west1-docker.pkg.dev/robusta-development/development/robusta-runner-dev:2900d85

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: a65d5d38-73ab-430a-a9ae-8e9ebfe5ef4d

📥 Commits

Reviewing files that changed from the base of the PR and between d9310b4 and f876268.

📒 Files selected for processing (2)

• docs/platform/index.rst
• docs/platform/triggered-workflows.rst

🚧 Files skipped from review as they are similar to previous changes (2)

• docs/platform/index.rst
• docs/platform/triggered-workflows.rst

---

Walkthrough

Adds comprehensive documentation for Alert Triage, Incident Grouping, and Triggered Workflows, plus a Platform landing page, navigation entries, and cross-references throughout existing documentation.

Changes

Platform documentation

Layer / File(s)	Summary
Alert Triage documentation docs/platform/alert-triage.rst, docs/configuration/exporting/send-events-api.rst, docs/how-it-works/architecture.rst, docs/index.rst	Documents triage stages, investigation behavior, configuration, statuses, agent selection, delivery settings, and limitations, with related references added elsewhere.
Incident Grouping documentation docs/platform/incident-grouping.rst, docs/notification-routing/notification-grouping.rst, docs/how-it-works/oss-vs-saas.rst	Documents AI-based incident grouping, recurring-incident attachment, scale behavior, and distinctions from notification grouping and duplicate detection.
Triggered Workflows documentation docs/platform/triggered-workflows.rst, docs/configuration/exporting/robusta-pro-features.rst, docs/configuration/exporting/send-events-api.rst	Documents workflow creation, webhook usage, filtering, cluster overrides, delivery, limits, outcomes, and constraints.
Platform navigation and landing page docs/platform/index.rst, docs/index.rst	Adds the Platform landing page, feature cards, and navigation links for the platform documentation.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• robusta-dev/robusta#2108: Overlaps on documenting cluster behavior for webhook-based investigations.
• robusta-dev/robusta#2117: Also updates Send Events API documentation and related platform references.

Suggested reviewers: naomi-robusta, aantn, moshemorad

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding Platform docs for Alert Triage, Incident Grouping, and Triggered Workflows.
Description check	✅ Passed	The description is directly about the same documentation additions and cross-links described in the changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch ezra/ROB-669

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/platform/index.rst`:
- Line 24: Qualify the Alert Triage wording to reflect that automatic
investigation is opt-in and limited to eligible or configured alerts. Update
docs/platform/index.rst lines 24-24 to avoid implying every alert is
investigated, and update docs/index.rst lines 80-80 to replace “every alert is
analyzed” with wording that preserves the opt-in/manual behavior.

In `@docs/platform/triggered-workflows.rst`:
- Around line 81-82: Update the ``token`` authentication documentation in the
triggered-workflows API-key sections to keep the ``Authorization`` header as the
preferred method and explicitly warn that query-string credentials can be
exposed in logs, proxies, browser history, and observability systems. Mark
query-token authentication as a last resort and include guidance to redact and
rotate exposed keys.
- Line 121: Clarify the workflow request contract in the triggered-workflows
documentation: state whether the type parameter is required, accepted, or
ignored, then update the workflow URL examples and the 400-error description to
consistently reflect that decision. Keep the existing workflow_id validation and
later type=alert limitation aligned with the documented behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 535b2591-6178-4dc9-ad24-b1ef6fafc5bf

📥 Commits

Reviewing files that changed from the base of the PR and between 904bd04 and d9310b4.

📒 Files selected for processing (10)

• docs/configuration/exporting/robusta-pro-features.rst
• docs/configuration/exporting/send-events-api.rst
• docs/how-it-works/architecture.rst
• docs/how-it-works/oss-vs-saas.rst
• docs/index.rst
• docs/notification-routing/notification-grouping.rst
• docs/platform/alert-triage.rst
• docs/platform/incident-grouping.rst
• docs/platform/index.rst
• docs/platform/triggered-workflows.rst