Skip to content

How it works

Five stages, each with a gate that can stop the issue going further.

flowchart LR
    Sentry -->|issue alert| Receiver[Alert receiver]
    Receiver -->|card| Teams[Microsoft Teams]
    Receiver -->|fires| Routine[Unattended session]
    Routine -->|findings| Receiver
    Receiver -->|grants| Routine
    Routine -->|fix patch| Receiver
    Receiver -->|pull request| Repo[Target repo]
    Routine -->|issue operations| Receiver
    Receiver -->|issue| Repo

Sentry webhooks each issue alert to the receiver. The receiver verifies the HMAC signature, parses the alert, renders an Adaptive Card, and posts it to the Teams channel configured for that environment.

It posts through its own bot identity rather than through an incoming webhook, and that choice is load-bearing: posting as a bot returns the message id synchronously, which is what makes every later step able to reply in the same thread. Findings and autofix outcomes land under the alert they belong to instead of as loose messages.

An alert is worth investigating when three things hold: it is a kind Sentinel investigates, it is in an environment you asked to investigate, and its release resolves to a commit SHA.

The kinds are every level from warning up, plus two of the performance issues Sentry files at info: N+1 Query and N+1 API Call. Most performance issues are design work, a large payload that wants pagination or a slow query that wants an index, and an unattended session should not attempt that. An N+1 is a loop issuing one query or request per item, and the fix belongs where the loop is. Any other card says it is not auto-investigated, and the gate and that footer read the same rule, so they cannot disagree.

That third condition is stricter than it sounds. Investigating at the release SHA is the whole point, because it is the code that actually produced the error. If a release cannot be resolved to a commit, the alternative would be investigating the default branch instead, which is a different program than the one that crashed. Sentinel skips the issue rather than doing that.

Eligible alerts are enqueued with a debounce, so a deploy that lights up nine related issues becomes one batch rather than nine sessions.

The enqueue is also the skip cache: one investigation per issue, per environment, per release. Sentry sends repeats on purpose, since a frequency rule re-fires for as long as an issue stays hot, and each repeat posts a card of its own. Investigating that card would read the same code and reach the same findings, so a repeat on an unchanged release answers its own thread with a pointer to the thread that has them. The one exception is an earlier attempt that failed: the next repeat takes the row over and runs the investigation again under the new card, once. A new release gets a fresh row, because the code changed and the findings may too.

Every minute a sweep groups due issues by project and release, respects the per-sweep and daily fire caps, and fires one session per batch. The session checks the repository out at the release SHA, investigates each issue in the batch, and posts a findings document back to the receiver, which renders it as a reply in the alert’s thread.

Each finding carries an urgency rating, from urgent down to low, judged against the target repository’s own meanings for its issue priorities, or against generic defaults when the repository defines none. An issue seen only outside production is rated one level lower than the same evidence would earn in production, and never urgent, because it is not reaching users yet. Urgency leads the reply’s status line, so a reader scanning the channel knows what to open first. The receiver shows and records the rating but never acts on it: the autofix gate below does not read it.

A batch whose findings never arrive is failed loudly into the thread once its deadline passes. This matters more than it looks: the failure mode you cannot see is a session that dies quietly and leaves an alert looking investigated when nothing happened.

A finding proceeds to autofix only when every one of these holds: confidence and fixability each clear their configured minimums, its intent is settled, the project is on the allowlist, no cited file matches a forbidden or excluded path, no fix has already been attempted for that issue in that environment on that release, and the daily pull-request cap has budget left.

Intent is the signal fixability cannot stand in for. Fixability says how contained a change would be; intent says whether the right behavior is already decided. It is settled only when the behavior the fix restores is already recorded somewhere authoritative (the product code or its comments, a merged pull request, a design doc, a repository rule) and the fix brings the out-of-date side in line with it. The finding must name that source, and the reply card shows it under Details. Code that fails on purpose is itself a decision: when a lookup deliberately raises on a missing entry, supplying the entry meets that decision, while a fallback value is a smaller change that chooses new behavior. If choosing the right behavior needs a person, the finding does not earn a fix, however small the change.

When it does, the fix happens in the session that just reported the finding, not in a second one afterwards. The receiver answers the findings POST with one grant per approved finding: a dispatch id and a one-time callback token, with the repository, the base branch, and the callback URL alongside. No credential is in that response.

The reason it travels that way is worth stating plainly, because it shapes everything else: the receiver can answer a session that calls it, but it cannot message a session that is already running. The response body is the only channel there is.

The session then checks out the base branch, confirms the defect is still there and that the branch has not moved in ways that invalidate the diagnosis, writes the fix and a test that fails without it, and sends the change back to the receiver as a patch against the base commit, with the pull request title and body. A patch is as large as the change, not as the files it touches, so a fix to a large generated file still travels. The receiver checks every path against the same policy the gate uses, mints a token scoped to one repository and two permissions, applies the patch to the base commit exactly or not at all, builds one commit on a new branch through GitHub’s API, opens the pull request as the App, and posts the link into the Teams thread. The commit message and the pull request body both end with a Fixes <short id> line naming the issue the grant was for, so Sentry resolves that issue in the first release that ships the merge. A grant that never reports is failed into the thread once its hour is up.

The gate stays on the receiver rather than moving into the session, and so does every GitHub write: the session reads as the operator through the platform’s GitHub tools, holds no write credential, and never pushes. The security model explains why both of those matter.

A finding that ends without a pull request is filed as a GitHub issue, so it is tracked somewhere other than a chat thread. That covers a finding the gate did not grant, a partial or failed investigation, and a fix attempt that stopped short. A finding sent back as a finished fix is never filed, even when the receiver then fails to open the pull request, because that failure is the receiver’s own.

The session asks the receiver to search the target repository’s issues for one that already describes the same defect, and reads the likely matches with a read-only GitHub tool. It comments on a duplicate, reopens a closed one whose fix the investigated release already contains, or files a new issue the way the repository’s own issue conventions describe, with a Priority taken from the finding’s urgency and links to related issues. It makes none of those writes itself. It asks the receiver for each one by name, under a token issued with the findings for that one alert, and the receiver makes the write as the App and links the issue in the alert’s thread.

Defaults as they ship in config/receiver.yaml.example.

Gate Default What it does
trigger_mode shadow Runs the gate and records what would have fired, firing nothing
environments prod, staging Which Sentry environments are investigated at all
investigation.debounce_seconds 60 How long a new issue waits, so related issues batch
investigation.max_batch_issues 8 Most issues handed to one session
investigation.per_sweep_fire_cap 4 Most sessions fired in one minute
investigation.daily_fire_cap 40 Most sessions fired in a day
investigation.deadline_seconds 900 After this, the batch is failed into the thread
caps.max_turns 50 Hard ceiling on one unattended session
autofix.enabled false Whether findings can open pull requests at all
autofix.min_confidence high Minimum confidence for a fix attempt
autofix.min_fixability medium Minimum fixability for a fix attempt
autofix.exclude_paths empty Cited paths that veto a fix attempt
autofix.daily_pr_cap 5 Most pull requests opened in a day
issues.enabled false Whether a finding that ends without a pull request is filed as a GitHub issue

Every one of these is a config value, so tightening a gate is a deploy rather than a code change. Configure and deploy covers setting them. The intent check has no setting: a finding whose intent is not settled never earns a fix, whatever the other minimums are.

Every stage above has a way to fail that leaves an alert without the answer it was promised: a card that does not post, an investigation that never starts or never reports, a session that reports it could not investigate, a fix or an issue write that does not land. Each is an alarm on the receiver’s alarm topic, which emails the operator and can also publish to an ntfy topic, so a failure reaches someone even when nobody is reading the channel. The full list is in Runbooks.