Workers Builds notify
workers-builds-notify is the Cloudflare account listener for Workers
Builds. GitHub merges. Cloudflare builds. This Worker watches the build
that should follow the merge.
Two gaps need two paths:
- A build that starts and fails publishes
build.failed. - A merge that should build, but never does, publishes nothing.
Event Subscriptions cover the first case. The build.missing watchdog
covers the second.
Do not watch Builds from a Cursor Cloud Agent session.
Failed builds
Section titled “Failed builds”Workers Builds Event Subscriptions write build.failed to a Queue in
the Cloudflare account. The notify Worker consumes that Queue.
A failed build cannot change production. The alert exists so an owner fixes the build or keeps the healthy release. See Cloudflare deployment and Observability.
Missing builds
Section titled “Missing builds”Event Subscriptions fire only when a build exists. They cannot detect a skipped, dropped, or never-created production build.
The watchdog covers that gap.
GitHub push webhook
Section titled “GitHub push webhook”An organization-level GitHub push webhook posts to
POST /webhooks/github-push on workers-builds-notify.mnppi.workers.dev.
GitHub signs the body with HMAC-SHA256 in X-Hub-Signature-256.
The Worker verifies that header against the Worker secret
WATCHDOG_WEBHOOK_SECRET.
The path is tokenless. It does not use a GitHub PAT. It does not call the GitHub API.
On a valid push, the Worker writes the commit SHA and the changed files to a KV inbox.
Path match and grace
Section titled “Path match and grace”A 10-minute cron reads the inbox. It matches changed files against each
Workers Builds trigger’s path_includes and path_excludes.
After a 15-minute grace from the merge, it looks up Cloudflare Builds
by commitHash. If a matched trigger has no build, the Worker alerts.
build.missing alert
Section titled “build.missing alert”The alert kind is build.missing. Fields:
| Field | Meaning |
|---|---|
worker |
Workers Builds trigger that should have run |
repo |
GitHub repository |
sha |
Merged commit |
matchedPaths |
Changed files that matched the trigger paths |
minutesSinceMerge |
Age of the merge when the check ran |
The Worker sends that payload to the Grok webhook. It also sends email
through @mnppi/email-layout and Cloudflare Email Sending. Use
BRAND_PRESETS.mnppi for notify.mnppi.org and other MNPPI ops alerts.
CID-embed logos by default. Mail is non-success only. There is no
Resend path.
Dedup and drift
Section titled “Dedup and drift”KV dedup allows one re-alert at 60 minutes if the build is still missing. It does not send a new alert on every cron tick.
A daily drift reconciler compares Cloudflare Builds against the last main SHA stored in KV. That job covers inbox loss or a missed webhook.
Secrets and ownership
Section titled “Secrets and ownership”Declare WATCHDOG_WEBHOOK_SECRET in secrets.required. Set the value
in the Cloudflare dashboard. See
Worker secrets and vars.
Do not put the webhook secret in GitHub Actions. Do not store a GitHub PAT on this Worker for the watchdog path.
Workers Builds still owns production deploy for the notify Worker itself. Merge is not deploy.
Anti-patterns
Section titled “Anti-patterns”Pointers
Section titled “Pointers”- Cloudflare deployment — Builds owns production. Merge is not deploy.
- Observability — Delivery alerts need an owner and a first action.
- Release and recovery — Confirm the merged commit actually built.
- Coding agents — HTML email uses
@mnppi/email-layoutand CID-embed logos. - Worker secrets and vars — Secret names only. Values stay in Cloudflare.
- Git home:
MNPPI/workers-builds-notify. Thebuild.missingwatchdog shipped in pull request 12.