Configure and deploy
The config file
Section titled “The config file”Copy the template and fill it in:
cp config/receiver.yaml.example config/receiver.yamlconfig/receiver.yaml stays out of git; only the .example template ships. Replace
every REPLACE_WITH_* value before deploying. The CDK app runs assert_ready before
synth and refuses to deploy while any placeholder remains, so a half-filled config
fails loudly rather than deploying something inert.
The knobs that matter
Section titled “The knobs that matter”Defaults are the template’s own. The inline comments below are quoted from it, because the template is the source of truth.
| Key | Default | What it means |
|---|---|---|
trigger_mode |
shadow |
auto fires on every eligible notification; shadow runs the gate and records what would have fired, firing nothing |
environments |
prod, staging |
“Name the ones you run here; the per-developer dev envs are best excluded: stale/unpushed release SHAs make release-checkout structurally wrong” |
target_repo |
placeholder | “Repository the routine session investigates (must match the routine’s repository binding; the startup assertion enforces this)”. Fixes land here too; there is no separate autofix repository |
release_to_sha |
identity |
“For many projects the release IS the commit SHA. Other projects may need a lookup” |
caps.max_turns |
50 | “Hard caps for an unattended session” |
investigation.debounce_seconds |
60 | How long a new issue waits, so related issues batch into one session |
investigation.max_batch_issues |
8 | Most issues handed to a single session |
investigation.per_sweep_fire_cap |
4 | Most sessions fired in one sweep |
investigation.daily_fire_cap |
40 | Most sessions fired in a day |
investigation.deadline_seconds |
900 | After this, the batch is failed loudly into the thread |
investigation.findings_url |
placeholder | “The receiver’s own Function URL, which does not exist until the first deploy” |
payload_mode |
issue-ids-only |
“The only supported mode: a full event body can exceed the 65,536-character fire cap” |
autofix.enabled |
false |
“enabled false ships the code inert; turning it on is a config deploy” |
autofix.min_confidence |
high |
Minimum finding confidence for a fix attempt |
autofix.min_fixability |
medium |
Minimum fixability for a fix attempt |
autofix.projects |
[] |
Allowlist; “an empty allowlist opts in every project” |
autofix.exclude_paths |
[] |
A cited path matching any of these vetoes the attempt, on top of the paths under .github/ that are always forbidden |
autofix.daily_pr_cap |
5 | Most pull requests opened in a day |
autofix.app_id |
placeholder | The autofix GitHub App’s numeric id; its private key is an SSM parameter, never config |
autofix.base_branch |
placeholder | “The branch fixes are written against and PRs target. The fix lands in target_repo (above); there is no separate dispatch repository since the fix session runs inside the investigation routine” |
autofix.callback_url |
placeholder | The receiver’s /autofix-result route, where the fix session reports each grant’s outcome |
The last three are required only once autofix.enabled is true, and assert_ready
refuses to deploy while any of them is still a placeholder.
Issue filing has its own block, inert as shipped:
| Key | Default | What it means |
|---|---|---|
issues.enabled |
false |
“enabled false ships the code inert; turning it on is a config deploy” |
issues.environments |
[] |
“Sentry environments whose outcomes are filed. Empty means every environment above; name one to stage the rollout” |
issues.proxy_url |
placeholder | “The receiver’s issue route. Must share findings_url’s origin” |
issues.conventions |
[] |
“Repository-relative files in target_repo that say how an issue is filed there, including what each priority means. They are written into the investigator prompt when it is pasted, and the session reads them from its checkout; nothing here mirrors them” |
issues.issue_types |
[] |
“Issue types a new issue may carry, by name. Empty means none” |
issues.fields |
[] |
“Organization issue fields the receiver may set, by name. Any other field is refused” |
issues.project_number |
0 | “The organization project board new issues join, owned by target_repo’s owner. 0 means no board” |
issues.daily_create_cap |
25 | “Ceilings on the receiver’s issue writes per UTC day, across all alerts”: the issues it creates |
issues.daily_write_cap |
100 | The same ceiling for every write, comments and field values included |
With issues.enabled true, assert_ready refuses to deploy unless proxy_url is set
and shares findings_url’s origin, autofix.app_id is set (the autofix App makes every
issue write, even with autofix off), conventions names at least one file and no
placeholder, every environments entry is one of the top-level environments, and the
board number and the caps are integers. fields and project_number need an
organization-owned target_repo; for a user-owned one, leave fields empty and
project_number at 0.
Note the ordering problem in investigation.findings_url: it is the receiver’s own
Function URL, which does not exist until the first deploy. That is precisely why
trigger_mode ships as shadow. Deploy once, read the stack output, fill it in,
deploy again, then soak before switching to auto.
Secrets
Section titled “Secrets”Secrets never go in the config file. It carries only trigger.token_ref and
trigger.probe_token_ref, the names of the SSM keys (under webhook.ssm_prefix) that hold
the routine trigger tokens. The config file ships inside the Lambda bundle, so the receiver
refuses to load a config whose ref looks like a token rather than a key name. The
parameters themselves are SecureStrings written by:
BOT_CLIENT_SECRET='...' \SENTRY_WEBHOOK_SECRET='...' \SENTRY_API_TOKEN='...' \ scripts/put-parameters.shAlarms go to aws.alarm_email. They can also be published to an ntfy topic, which is
optional and off as shipped:
# Optional. An ntfy server (for example https://ntfy.sh) to publish every # alarm to, as well as emailing it. Set it and a forwarder function is # deployed; leave it out and there is none. The topic is a secret, kept in # the <ssm_prefix>/ntfy-topic SecureString, never here. # alarm_ntfy_server: https://ntfy.shWrite the topic with NTFY_TOPIC='...' added to the put-parameters.sh run above. The
setup and the test are in Runbooks.
The one value in the config that looks like a secret and is not is
observability.automation_dsn. A Sentry DSN is ingest-only, so it lives in config and
CDK passes it through as SENTRY_DSN.
Deploy
Section titled “Deploy”The CDK app and its commands live beside the code they deploy, in
infra/README.md.
It covers the prerequisites, the cdk deploy sequence, the health check, and rollback.
The stack outputs FunctionUrl. Its two routes go to the two setup stages:
<FunctionUrl>sentrybecomes the Webhook URL on the Sentry integration<FunctionUrl>botbecomes the Messaging endpoint on the Azure Bot
Turning it on
Section titled “Turning it on”Moving trigger_mode from shadow to auto is a config change plus a deploy, and it
should follow a soak: leave it in shadow long enough to see the gate make decisions on
real traffic, then read what it recorded before letting it fire.
Autofix is a second, separate switch. autofix.enabled: true should follow its own soak
on findings you have read, because it is the one gate whose output lands in somebody
else’s repository.
Issue filing is the third. issues.enabled: true files every investigated finding that
ends without a pull request in target_repo’s issues, through the receiver and as the
App. Stage it with issues.environments, naming one environment first. It needs the App
to hold three more permissions, accepted by an organization owner: Issues read and
write, organization Projects read and write, and organization Issue fields read-only.
The order of the steps, and how to undo each, is the
enabling issue filing runbook.
Three things outside this file have to be true before it can work: the autofix App must
be installed on target_repo with contents and pull-requests write, the routine’s cloud
environment must be allowed to reach GitHub, and target_repo’s dependencies must be
installed in the routine’s sessions, because the fix phase runs its test and may not
install anything. The first two are covered in the
runbooks. For the third, the recommended way is a
SessionStart hook in that repository, with the environment’s setup script prebuilding
the dependencies so the hook only has to link them into place.