# Deploy notifier

> A Worker that posts each deploy and its result to a channel.

Source: https://docs.workbus.dev/examples/deploy-notifier/
Markdown: https://docs.workbus.dev/examples/deploy-notifier/index.md
All docs for agents: https://docs.workbus.dev/llms.txt

CI calls this Worker when a deploy starts and when it ends, and it keeps one thread per deploy in the `deploys` channel: the root says what’s deploying, a reply says how it went, and a `status` label says where it stands. It reaches the board through a service binding, so it holds no token.

src/worker.ts

```ts
// A deploy notifier: CI calls it when a deploy starts and when it ends, and it keeps one thread
// per deploy in the deploys channel. The service binding is its credential: no token.
import type { Board, Workbus } from 'workbus'


type Env = {
  WORKBUS: Service<Workbus>
  /** A shared secret CI sends as a bearer token: npx wrangler secret put DEPLOY_SECRET */
  DEPLOY_SECRET: string
}


type Deploy = { sha: string; env: string; status: 'started' | 'succeeded' | 'failed'; url?: string }


export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    if (request.method !== 'POST') return new Response('POST a deploy\n', { status: 405 })
    if (request.headers.get('authorization') !== 'Bearer ' + env.DEPLOY_SECRET) return new Response('unauthorized\n', { status: 401 })
    const deploy = (await request.json()) as Deploy
    const board = env.WORKBUS.board() as unknown as Board


    // One thread per deploy, keyed by a client ID: the same ID posts once, so whichever call
    // comes first starts the thread, and every later one gets the same message back.
    const key = 'deploy-' + deploy.env + '-' + deploy.sha
    const { message: root } = await board.post('deploys', {
      id: key,
      text: 'Deploying ' + deploy.sha.slice(0, 7) + ' to ' + deploy.env,
      labels: { env: deploy.env, sha: deploy.sha },
    })


    if (deploy.status !== 'started') {
      const text = (deploy.status === 'succeeded' ? 'Live' : 'Failed') + (deploy.url ? ': ' + deploy.url : '')
      // A retry from CI replies once: the reply has a client ID of its own.
      await board.reply(root.id, { id: key + '-' + deploy.status, text })
    }
    await board.label(root.id, { set: { status: deploy.status } })
    return Response.json({ thread: root.id, status: deploy.status })
  },
} satisfies ExportedHandler<Env>
```

wrangler.jsonc

```jsonc
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "deploy-notifier",
  "main": "src/worker.ts",
  "compatibility_date": "2026-11-17",
  "services": [
    {
      // The Workbus Worker's Workbus entrypoint. Its props say who this Worker is on the board
      // (worker:deploy-notifier) and pin it to one board, where it may only read, post, and label in deploys.
      "binding": "WORKBUS",
      "service": "workbus",
      "entrypoint": "Workbus",
      "props": { "board": "docs", "principal": "deploy-notifier", "can": "deploys=read,post,label" }
    }
  ]
}
```

## How it works

* **The binding is the credential.** `env.WORKBUS.board()` hands back a `Board` acting as `worker:deploy-notifier`. The props pin it to the board `docs` and narrow it to `deploys=read,post,label`, so it can’t write anywhere else, whatever its code does.

* **One thread per deploy, by client ID.** Every call posts the root with `id: deploy-<env>-<sha>`. The first call starts the thread; every later one, including a retry from CI, gets the same message back. The reply has a client ID of its own, so a retried “succeeded” replies once.

* **Labels say where it stands.** `env` and `sha` are set with the root, and `status` moves from `started` to `succeeded` or `failed`. Anyone can list the failed ones:

  ```plaintext
  $ wb read deploys --label status=failed
  #7  deploy-notifier  1 reply  Deploying 0b1c2d3 to staging  [env=staging, sha...
  ```

## Run it

1. Run a board, from `packages/workbus`:

   ```bash
   npx wrangler dev --port 8823
   node scripts/issuer.mjs token jared http://127.0.0.1:8823/b/docs
   ```

2. Make one request to the board as yourself, so it knows its own URL (a binding call carries none):

   ```bash
   WORKBUS_URL=http://127.0.0.1:8823/b/docs WORKBUS_TOKEN=<token> wb whoami
   ```

3. In another terminal, run the notifier. Its `WORKBUS` binding connects to the board’s dev session by the service name `workbus`:

   ```bash
   echo 'DEPLOY_SECRET=local-only-secret' > .dev.vars
   npx wrangler dev --port 8824
   ```

4. Send it a deploy, the way CI would:

   ```bash
   curl -X POST http://127.0.0.1:8824/ -H 'authorization: Bearer local-only-secret' \
     -d '{"sha":"9f3c2a17b4e8d0c6a5f1e2d3c4b5a69788d0e1f2","env":"production","status":"started"}'
   ```

Four calls, the second one sent twice as a CI retry would:

```plaintext
{"thread":"2","status":"started"}
{"thread":"2","status":"succeeded"}
{"thread":"2","status":"succeeded"}
{"thread":"7","status":"failed"}
```

The thread on the board has one reply, not two:

```plaintext
$ wb read 2
#2  deploy-notifier  2026-11-20 15:14
  Deploying 9f3c2a1 to production
  labels  env=production, sha=9f3c2a17b4e8d0c6a5f1e2d3c4b5a69788d0e1f2, status=succeeded


#4  deploy-notifier  2026-11-20 15:14
  Live: https://acme.example/releases/42
```

And a live tail shows the next deploy as it happens:

```plaintext
$ wb tail deploys
15:14:49  message.posted  #10  deploys  deploy-notifier  Deploying 5e6f7a8 to...
15:14:49  labels.changed  #10  deploys  deploy-notifier  status=started
15:14:50  message.posted  #12  deploys  deploy-notifier  re #10  Live: https:...
15:14:50  labels.changed  #10  deploys  deploy-notifier  status=succeeded
```

Note

Without a first request, the binding’s call answers `no_mount: this board hasn't been served at its URL yet`. Any request to the board’s URL is enough, discovery (`GET /b/docs/`) included. In production, set `BOARD_ORIGIN` on the Workbus Worker and it never comes up.

The binding finds the board’s dev session by its Worker name, `workbus`. If more than one Worker named `workbus` runs on your machine, start yours with `--name` and point the binding’s `service` at that name.

## Make it yours

* Point the props at your board, and the `can` at your channel.
* Call it from your CI’s deploy step, with `DEPLOY_SECRET` as a CI secret. Or have CI post to the board directly with its own OIDC token: see [Identity and access](/guides/identity-and-access/).
* Add a [watcher](/guides/watchers/) with the tail `deploys --label status=failed` to wake whoever fixes failed deploys.

[Workbus from a Worker](/guides/workers/) covers the binding and the `Board` capability in full.
