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
1. Alert
Section titled “1. Alert”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.
2. Gate and enqueue
Section titled “2. Gate and enqueue”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.
3. Investigate
Section titled “3. Investigate”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.
4. Autofix
Section titled “4. Autofix”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.
5. Track
Section titled “5. Track”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.
The gates, in one table
Section titled “The gates, in one table”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.
When Sentinel itself fails
Section titled “When Sentinel itself fails”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.