Repository navigation
feat(ops-mission-control): add an incident.io provider - #4951
Conversation
78eca09 to
82a2391
Compare
Design Review (Fable 5, fork) — ✅ PASSDesign-level review of Design-Verdict: PASS Verify the [DESIGN-REVIEWED] 5b831cc |
GPT 5.6 Review (fork) — ✅ no blocking findingsReviewed Review detailsFINDING -- src/kiro_crew/apps/builtins/ops_mission_control/tests/test_config_routes.py:385 -- method-local |
First Principles Review (Fable 5, fork) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS Every incident.io API shape the adapter rests on — pagination, schedule Not justified as shipped
What this change shipsInventory (10 items) — 6 justifiedIntent: let an operator whose alerting lives in incident.io get those alerts onto the Ops Mission Control board, with rotation and actions — an ADDITION.
[FIRST-PRINCIPLES-REVIEWED] 5b831cc |
UX Review (Fable 5, fork) — 🟡 CONCERNSUX-level review of UX-Verdict: CONCERNS No first-time reader has seen the new identity field or refusal copy, and three changed error strings were never shown rendered. Watch
Suggestions
[UX-REVIEWED] 5b831cc |
Opus 4.8 Review (fork) — ✅ no blocking findingsReviewed Review detailsI've verified the load-bearing facts myself: Tracing the pagination loop by hand against each edge (empty-page-with-cursor → truncated; terminal overshoot → cap break then post-loop No findings. [OPUS-REVIEWED] 5b831cc |
82a2391 to
b92bce9
Compare
|
Both blocking findings land in
|
Head branch was pushed to by a user without write access
b92bce9 to
ba794aa
Compare
|
🤖 Kiro Crew [operator: NicholasRBowers#a942f9ca] Round 3 on
Verified locally: tsc, eslint, both i18n gates, comment-history gate, 156 ops frontend tests (75 in the settings file, incl. the 2 new pins). Rebased onto current main (#7237); single commit, Stephen Meehan preserved as author. |
|
self-added: no
|
|
self-added: yes
|
Registers `incidentio` as a public adapter implementing SignalSource, RotationSource and ActionSink over the incident.io REST API. Built on alerts rather than incidents: an alert's status is a strict firing/resolved enum, which is the same shape as a signal's own lifecycle, so absence from a poll means it cleared. A declared incident is a human artefact whose transitions run a post-incident flow, and putting one on the board would duplicate work a responder already owns. The sink offers `resolve` and `comment` only. The API has no acknowledged state and no snooze, mute or suppress call for a single alert, and advertising a verb the provider cannot perform would pass the autonomy gate and then fail at execute time, after the board had recorded the action as granted. Truncation is detected from the response cursor, not by fetching one item past the cap: 50 is the endpoint's maximum page size, so a larger request is clamped and reads back as a complete page. Alert-source filtering runs client-side because the documented filter's multi-value encoding is not specified, and a guessed encoding that matches nothing presents as a quiet estate; the truncation verdict is therefore taken from the raw response and survives filtering. The rotation identity lives on the keystone (`incidentio.user_id`), not in provider config. incident.io has no self-identity endpoint, so it cannot be derived at runtime, and provider config is agent-writable — a forged identity there would let the constrained party claim the shift and authorize a write it does not own. A source with no identity abstains rather than voting off shift, and an empty (agent-writable) schedule list with an operator identity present votes off shift rather than manufacturing an abstention. Co-authored-by: Kiro Crew <noreply@kirodotdev.github.io>
2f9b5d0 to
5b831cc
Compare
|
🤖 Kiro Crew [operator: NicholasRBowers#a942f9ca] Round 4 on
Verified locally: 22 backend provider tests (incl. 3 new, one proven red-first), 76 settings-panel tests, tsc/eslint, black/isort/flake8, both i18n gates, comment-history gate. Rebased onto current main (#11050); single commit, Stephen Meehan preserved as author. |
|
self-added: no
|
|
self-added: no
|
|
self-added: yes
|
|
self-added: no
|
|
self-added: yes
|
|
self-added: yes
|
|
self-added: yes
|
|
self-added: no
|
|
self-added: yes
|
|
self-added: no
|
|
self-added: no
|
|
self-added: yes
|
|
self-added: yes
|
|
self-added: yes
|
|
Reviewed on the current head for approval.
|
Problem / Motivation
Ops Mission Control can ingest signals from CloudWatch, Datadog, GitHub Issues and a
generic webhook, but not from incident.io. An operator whose alerting already lives in
incident.io has no way to get those alerts onto the board: they cannot be claimed,
investigated, fingerprinted against the knowledge ledger, or resolved through the app.
The on-call schedule is equally invisible, so the rotation tier has nothing to consult
for an incident.io-based team.
Why it matters
Without a provider, an incident.io shop gets no value from the board at all — the
signals it needs to triage are exactly the ones the app cannot see. Adding it also
exercises the provider seam a second time for a rotation-capable source, which is where
the authorization boundary lives.
What changed (motivation → approach → change)
Goal: make incident.io a first-class source — signals, rotation and actions —
without weakening the existing authorization model.
Approach, and why this shape:
firing/resolvedstatus, which is the same shape as a signal's own lifecycle, soabsence from a poll is meaningful. A declared incident is a human artefact with an
eight-category status whose transitions run a post-incident flow; putting one on the
board would duplicate work a responder already owns.
resolveandcommentare offered. The API has no acknowledged state andno snooze/mute/suppress for a single alert (a maintenance window is account-level
config). Advertising
ackorsilencewould pass the autonomy gate and then fail atexecute time, after the board had recorded the action as granted.
incident.io has no self-identity endpoint — an API key resolves to the key, not a
person — so the operator's own user id cannot be derived at runtime. Provider config
is agent-writable, so an identity living there could be forged to claim the shift and
authorize a write it does not own. It sits in
policy_store.OPERATOR_ONLY_KEYSasincidentio.user_id, written only by the authenticatedPUT /settings, exactly likepagerduty.user_id. The write goes through_settings_write_or_refuse, the samepath as every sibling keystone write on that route, so a store that cannot be
written answers with a coded 503 instead of aiohttp's bare 500 — and the Settings
panel renders that refusal through
ErrorNotice, keeping the unsaved draft in theinput, so an operator is never left believing an identity landed when it did not.
A shared helper maps the coded refusals to task vocabulary instead of surfacing the
raw backend reason:
policy_store_unwritablebecomes "Your ID was not saved — thesettings store refused the write. Retry." (naming the refuser, so a persistently
failing retry has a diagnosis), and the
value_too_longvalidation 400 loses itssnake_case settings key. The same helper covers the schedule-login and app-settings
notices, which receive the same coded 503 from the same route; uncoded failures keep
their backend reason verbatim. The identity help string states the off-shift
consequence of an ID with no schedules configured, so the operator is told before
entering that state.
ShiftStatus(on_shift=True, unknown=True)),matching the documented
unknowncontract inproviders/base.pyand PagerDuty's ownabstention branches. An empty agent-writable
schedule_idswith an operatoridentity present votes off shift instead, so a config write cannot manufacture the
abstention the tier gate treats as a non-vote.
The alerts endpoint caps a page at 50, well under the registry's 100-signal cap, so
a single-page read would report any estate over 50 firing alerts as a truncated poll
on every cycle — permanently non-authoritative, so
reconcilecould never resolveone of this source's signals. The walk pages until the estate is exhausted, and the
verdict is computed once, after the loop, from whether the final slice actually
discarded anything — never from whichever branch ended the walk, so "dropped an
alert but called the poll complete" is unrepresentable. The source filter runs
inside the walk, before the cap, so both the cap and the verdict are spent only on
alerts the board would see: a storm of alerts from unselected sources can neither
evict a selected firing alert from the poll nor mark a fully walked, non-matching
estate as truncated. A page ceiling
(
_MAX_ALERT_PAGES, mirroring CloudWatch's_MAX_ALARM_PAGES) bounds a providerthat keeps handing back a cursor without ever terminating: bounded out under the
cap, the poll raises — read by the registry as "incidentio did not answer" — rather
than reporting a partial estate as a complete snapshot.
Also: client-side filtering of
alert_source_ids(applied while paging, per thebullet above), because the endpoint documents an
alert_source[one_of]filter but nothow to encode multiple values, and a guessed encoding that matches nothing presents as
a quiet estate. The module spec's pagination
section now lists this walk beside the other four pollers, and its identity inventory
counts all three keystone-fenced identities.
Tests
tests/test_providers_incidentio.py(16 tests):empty agent-writable
schedule_idswith an operator identity present votes off shiftrather than abstaining; a genuinely unconfigured provider abstains and fails open; the
effective schedule (
final) decides rather than the pre-override rotation rules, soa covered shift is not read as ours.
supported_actions()is exactly{resolve, comment}, andack/silenceare refused without the provider ever being called.made and carries
after) rather than reported as truncation; an estate past the capreports truncated; a terminal page that overshoots the cap still reports truncated
(the regression guard for a dropped-but-called-complete poll); an estate of exactly
the cap is not truncated; an empty page carrying a cursor is truncation, while an
empty terminal page without one stays authoritative; client-side source filtering
preserves the verdict; a cursor that never terminates is bounded by the page ceiling
and refuses loudly instead of under-reporting.
provider_keywhenpresent, and the alert id is carried in labels for the action path.
tests/test_config_routes.pyadds a refusal test: a policy store that cannot bewritten answers the identity save with a coded 503 (
policy_store_unwritable) andstores nothing. Reverting the production change while keeping the tests makes the
refusal test and the overshoot guard fail; restoring it returns them green.
OpsMissionControlSettings.coverage.test.tsxpins the notice's branches: a codedkeystone refusal renders the task-vocabulary string with the draft still in the
input, the overlong-value refusal loses its snake_case key, and an uncoded failure
keeps its backend reason verbatim.
Three poll tests pin the filter-before-cap ordering: a selected-source alert survives
a 150-alert storm from unselected sources (fails with the slice applied before the
filter), the truncation verdict is derived from matching alerts, and a fully walked
estate that matched nothing is an authoritative empty.
Three existing tests in
tests/test_providers.pywere extended to assert the adapterregisters and reports unconfigured rather than raising.
Manual verification
Run against a real incident.io account in an isolated pod (own
KIROCREW_HOME, nocrons), not the live gateway. The provider polled 50 firing alerts and the Signals
tab showed the source
ok. That run is what surfaced the one-page truncation defectabove — 50 firing alerts is exactly one page, so the source was permanently
non-authoritative and no unit test had reason to notice.
The write verbs were not executed against a live account (none is available to this
revision); their endpoint shapes and the claims the verb set rests on are checked
against the vendor's public API reference at
api-docs.incident.io: Alerts, Alert Notes, Alert
Events and Schedule Entries are documented resources; no per-alert snooze, mute or
suppress endpoint exists anywhere on the surface (MaintenanceWindows is a separate,
account-level resource); and the pagination walk follows the reference's own cursor
contract verbatim (
pagination_meta.after, repeat until a page returns fewer recordsthan
page_size). A failed action degrades toActionResult(ok=False)on the board —graceful and reversible, never a silently-lost action.
The screenshots below are rendered at this revision with the repo's fixture-based
capture harness (mocked API, real SPA build), so they show the shipped strings —
including the current identity help text — rather than an earlier revision's UI.
Local gate floor green on this commit: pytest (1031 passed / 44 skipped in the app
suite, 33k-test diff-scoped run with no failure attributable to this diff), black
(baselined gate), isort, flake8, mypy (no errors in touched files),
tsc -b, eslint,vitest (304 ops-mission-control frontend tests), and
i18n:checkgreen across alllocales.
Screenshots / video
The provider card, showing the new keystone-fenced identity field, its help text, and
the roles the adapter registers:
The refused identity save — the keystone's coded 503 rendered in task vocabulary,
with the typed draft still in the input:
The Signals tab with the source polled and firing alerts on the board
(fixture-rendered at this revision):
Related Issues
no linked issue: this adds a provider that was not tracked by an existing issue.
Checklist
feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)