Skip to content

Configure and deploy

Copy the template and fill it in:

Terminal window
cp config/receiver.yaml.example config/receiver.yaml

config/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.

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 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:

Terminal window
BOT_CLIENT_SECRET='...' \
SENTRY_WEBHOOK_SECRET='...' \
SENTRY_API_TOKEN='...' \
scripts/put-parameters.sh

Alarms 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.sh

Write 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.

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>sentry becomes the Webhook URL on the Sentry integration
  • <FunctionUrl>bot becomes the Messaging endpoint on the Azure Bot

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.