---
title: "Workers Builds notify"
description: "Account Worker that alerts on Workers Builds failures and missing production builds. Tokenless GitHub push webhook, KV inbox, and Cloudflare Email."
url: "https://architecture.mnppi.org/operations/workers-builds-notify/"
status: "Current"
last_updated: "2026-10-14"
---

# Workers Builds notify

**Standard details**

- Status: Current
- Reviewed: October 14, 2026
- Cadence: Review after a Workers Builds notify change

`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

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](https://architecture.mnppi.org/delivery/cloudflare-deployment/index.md) and
[Observability](https://architecture.mnppi.org/operations/observability/index.md).

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

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

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

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

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

Declare `WATCHDOG_WEBHOOK_SECRET` in `secrets.required`. Set the value
in the Cloudflare dashboard. See
[Worker secrets and vars](https://architecture.mnppi.org/operations/worker-secrets-and-vars/index.md).

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

> **Caution — Do not**
>
> Do not watch Workers Builds from a Cursor Cloud Agent or a laptop
> session.
> Do not call the GitHub API from the watchdog path.
> Do not send success mail. Non-success only.
> Do not add Resend or a one-off HTML email shell.
> Do not invent a second account listener.

## Pointers

- [Cloudflare deployment](https://architecture.mnppi.org/delivery/cloudflare-deployment/index.md) — Builds owns
  production. Merge is not deploy.
- [Observability](https://architecture.mnppi.org/operations/observability/index.md) — Delivery alerts need an
  owner and a first action.
- [Release and recovery](https://architecture.mnppi.org/delivery/release-and-recovery/index.md) — Confirm the
  merged commit actually built.
- [Coding agents](https://architecture.mnppi.org/delivery/coding-agents/index.md) — HTML email uses
  `@mnppi/email-layout` and CID-embed logos.
- [Worker secrets and vars](https://architecture.mnppi.org/operations/worker-secrets-and-vars/index.md) —
  Secret names only. Values stay in Cloudflare.
- Git home: `MNPPI/workers-builds-notify`. The `build.missing` watchdog
  shipped in pull request 12.