Skip to content

Commit af61d92

Browse files
yomna-shoushayomna-shousha
committed
Add Workers Builds Notifications template
1 parent eb0b6c6 commit af61d92

File tree

13 files changed

+4234
-0
lines changed

13 files changed

+4234
-0
lines changed

‎workers-builds-notifications-template/.dev.vars.example‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Slack incoming webhook URL
2+
# Get this from: https://api.slack.com/apps → Your App → Incoming Webhooks
3+
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
4+
5+
# Cloudflare API token
6+
# Create at: https://dash.cloudflare.com/profile/api-tokens
7+
# Select:
8+
# - **Edit Cloudflare Workers** template
9+
CLOUDFLARE_API_TOKEN=your-api-token-here

‎workers-builds-notifications-template/.gitignore‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Dependencies
2+
node_modules/
3+
4+
# Build output
5+
dist/
6+
7+
# Wrangler
8+
.wrangler/
9+
.dev.vars
10+
11+
# TypeScript
12+
*.tsbuildinfo
13+
14+
# Logs
15+
*.log
16+
npm-debug.log*
17+
18+
# IDE
19+
.vscode/
20+
.idea/
21+
22+
# OS
23+
.DS_Store
24+
Thumbs.db

‎workers-builds-notifications-template/LICENSE‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
Copyright (c) 2025 Cloudflare, Inc.
2+
3+
Licensed under the Apache License, Version 2.0 (the "License");
4+
you may not use this file except in compliance with the License.
5+
You may obtain a copy of the License at
6+
7+
http://www.apache.org/licenses/LICENSE-2.0
8+
9+
Unless required by applicable law or agreed to in writing, software
10+
distributed under the License is distributed on an "AS IS" BASIS,
11+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
See the License for the specific language governing permissions and
13+
limitations under the License.

‎workers-builds-notifications-template/README.md‎

Lines changed: 292 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,292 @@
1+
# Workers Builds Notifications
2+
3+
[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/templates/tree/main/workers-builds-notifications-template)
4+
5+
<!-- dash-content-start -->
6+
7+
Get notified when your Workers Builds complete, fail, or are cancelled. This template uses [Queue Event Subscriptions](https://developers.cloudflare.com/queues/configuration/event-subscriptions/) to consume Workers Builds events and forward them to any webhook — Slack, Discord, or your own endpoint.
8+
9+
## Features
10+
11+
- 🔔 Real time notifications for build success, failure, and cancellation
12+
- 🔗 Works with any webhook (Slack, Discord, custom endpoints)
13+
- 📋 Includes build details: project name, status, duration, and other metadata
14+
- 📜 Optional build logs, preview URL, and live deployment URL fetched via Cloudflare API
15+
16+
## How It Works
17+
18+
1. Workers Builds emits events to a Cloudflare Queue
19+
2. This Worker consumes those events via Queue Event Subscriptions
20+
3. Build details are formatted and sent to your configured webhook
21+
22+
<!-- dash-content-end -->
23+
24+
## Getting Started
25+
26+
Outside of this repo, you can start a new project with this template using [C3](https://developers.cloudflare.com/pages/get-started/c3/) (the `create-cloudflare` CLI):
27+
28+
```bash
29+
npm create cloudflare@latest -- --template=cloudflare/templates/workers-builds-notifications-template
30+
```
31+
32+
---
33+
34+
## Setup
35+
36+
> **Important:** The queue must be created before deploying the worker.
37+
38+
### 1. Create a Queue
39+
40+
#### Option A: Via Dashboard
41+
42+
1. Go to [Queues](https://dash.cloudflare.com/?to=/:account/workers/queues)
43+
2. Click **Create Queue**
44+
3. Name it `builds-event-subscriptions` (or your preferred name)
45+
4. Click **Create**
46+
47+
#### Option B: Via CLI
48+
49+
```bash
50+
wrangler queues create builds-event-subscriptions
51+
```
52+
53+
> **Note:** The queue name must match what's in `wrangler.jsonc`:
54+
> ```jsonc
55+
> "queues": {
56+
> "consumers": [
57+
> {
58+
> "queue": "builds-event-subscriptions", // ← Must match your queue name
59+
> ...
60+
> }
61+
> ]
62+
> }
63+
> ```
64+
> If you use a different queue name, update `wrangler.jsonc` before deploying.
65+
66+
---
67+
68+
### 2. Deploy the Worker
69+
70+
#### Option A: Via Dashboard
71+
72+
1. Go to [Workers & Pages](https://dash.cloudflare.com/?to=/:account/workers-and-pages) → **Create** → **Import a repository**
73+
2. Connect your GitHub/GitLab and select this repository
74+
3. Deploy
75+
76+
#### Option B: Via CLI
77+
78+
```bash
79+
git clone https://github.com/cloudflare/templates.git
80+
cd templates/workers-builds-notifications-template
81+
npm install
82+
wrangler deploy
83+
```
84+
85+
---
86+
87+
### 3. Create a Webhook
88+
89+
#### Slack
90+
91+
1. Go to [Slack Apps](https://api.slack.com/apps) → **Create New App** → **From scratch**
92+
2. Name it (e.g., "Workers Builds Notifications") and select your workspace
93+
3. Go to **Incoming Webhooks** → Toggle **On**
94+
4. Click **Add New Webhook to Workspace** → Select your channel
95+
5. Copy the webhook URL
96+
97+
#### Discord
98+
99+
1. Go to your Discord server → **Server Settings** → **Integrations** → **Webhooks**
100+
2. Click **New Webhook** → Select your channel
101+
3. Copy the webhook URL
102+
4. Append `/slack` to the URL (Discord supports Slack-formatted payloads)
103+
104+
#### Other Webhooks
105+
106+
Modify the payload format in `src/index.ts` to match your webhook's expected format.
107+
108+
---
109+
110+
### 4. Create a Cloudflare API Token
111+
112+
1. Go to [Cloudflare API Tokens](https://dash.cloudflare.com/profile/api-tokens)
113+
2. Click **Create Token**
114+
3. Select **Edit Cloudflare Workers** template
115+
4. Click **Continue to summary** → **Create Token**
116+
5. Copy the token
117+
118+
---
119+
120+
### 5. Set Secrets
121+
122+
#### Option A: Via Dashboard
123+
124+
1. Go to [Workers & Pages](https://dash.cloudflare.com/?to=/:account/workers-and-pages)
125+
2. Select your deployed worker
126+
3. Go to **Settings** → **Variables and Secrets**
127+
4. Add:
128+
- `SLACK_WEBHOOK_URL` → Your webhook URL
129+
- `CLOUDFLARE_API_TOKEN` → Your API token
130+
131+
#### Option B: Via CLI
132+
133+
```bash
134+
wrangler secret put SLACK_WEBHOOK_URL
135+
# Paste your webhook URL
136+
137+
wrangler secret put CLOUDFLARE_API_TOKEN
138+
# Paste your API token
139+
```
140+
141+
---
142+
143+
### 6. Create an Event Subscription
144+
145+
Subscribe your queue to Workers Builds events.
146+
147+
#### Option A: Via Dashboard
148+
149+
1. Go to [Queues](https://dash.cloudflare.com/?to=/:account/workers/queues)
150+
2. Select your queue (`builds-event-subscriptions`)
151+
3. Go to the **Subscriptions** tab
152+
4. Click **Subscribe to events**
153+
5. Select source: **Workers Builds**
154+
6. Select events: All (or specific ones)
155+
7. Click **Subscribe**
156+
157+
#### Option B: Via CLI
158+
159+
```bash
160+
wrangler queues subscription create builds-event-subscriptions \
161+
--source workers-builds \
162+
--events build.started,build.succeeded,build.failed
163+
```
164+
165+
> For more details, see [Event Subscriptions Documentation](https://developers.cloudflare.com/queues/configuration/event-subscriptions/)
166+
167+
---
168+
169+
### 7. Test It!
170+
171+
Trigger a build on any worker in your account. You should see a notification in your channel within seconds!
172+
173+
---
174+
175+
## Architecture
176+
177+
```
178+
┌─────────────────┐ ┌─────────────┐ ┌──────────────────┐ ┌─────────┐
179+
│ Workers Builds │────▶│ Queue │────▶│ This Consumer │────▶│ Webhook │
180+
│ (any worker) │ │ │ │ Worker │ │ │
181+
└─────────────────┘ └─────────────┘ └──────────────────┘ └─────────┘
182+
```
183+
184+
1. **Any worker** in your account triggers a build
185+
2. **Workers Builds** publishes an event to your **Queue**
186+
3. **This consumer worker** processes the event and sends a notification to your **webhook**
187+
188+
---
189+
190+
## Event Types
191+
192+
| Event | Notification |
193+
|-------|--------------|
194+
| ✅ Build succeeded (production) | Live Worker URL |
195+
| ✅ Build succeeded (preview) | Preview URL |
196+
| ❌ Build failed | Build logs inline |
197+
| ⚠️ Build cancelled | Build logs inline |
198+
| 🚀 Build started | Build started |
199+
200+
---
201+
202+
## Event Schema
203+
204+
```json
205+
{
206+
"type": "cf.workersBuilds.worker.build.succeeded",
207+
"source": {
208+
"type": "workersBuilds.worker",
209+
"workerName": "my-worker"
210+
},
211+
"payload": {
212+
"buildUuid": "build-12345678-90ab-cdef-1234-567890abcdef",
213+
"status": "stopped",
214+
"buildOutcome": "success",
215+
"createdAt": "2025-05-01T02:48:57.132Z",
216+
"stoppedAt": "2025-05-01T02:50:15.132Z",
217+
"buildTriggerMetadata": {
218+
"buildTriggerSource": "push_event",
219+
"branch": "main",
220+
"commitHash": "abc123def456",
221+
"commitMessage": "Fix bug in authentication",
222+
"author": "[email protected]",
223+
"repoName": "my-worker-repo",
224+
"providerType": "github"
225+
}
226+
},
227+
"metadata": {
228+
"accountId": "your-account-id",
229+
"eventTimestamp": "2025-05-01T02:48:57.132Z"
230+
}
231+
}
232+
```
233+
234+
### Event Types Reference
235+
236+
| Event Type | Description |
237+
|------------|-------------|
238+
| `cf.workersBuilds.worker.build.started` | Build has started |
239+
| `cf.workersBuilds.worker.build.succeeded` | Build completed successfully |
240+
| `cf.workersBuilds.worker.build.failed` | Build failed |
241+
| `cf.workersBuilds.worker.build.failed` + `buildOutcome: "cancelled"` | Build was cancelled |
242+
243+
---
244+
245+
## Configuration
246+
247+
### Environment Variables
248+
249+
| Variable | Description |
250+
|----------|-------------|
251+
| `SLACK_WEBHOOK_URL` | Webhook URL (Slack, Discord, or custom) |
252+
| `CLOUDFLARE_API_TOKEN` | API token with Workers Builds and Scripts read access |
253+
254+
### Queue Settings (wrangler.jsonc)
255+
256+
| Setting | Default | Description |
257+
|---------|---------|-------------|
258+
| `max_batch_size` | 10 | Messages per batch |
259+
| `max_batch_timeout` | 30 | Seconds to wait for full batch |
260+
| `max_retries` | 3 | Retry attempts for failed processing |
261+
262+
---
263+
264+
## Troubleshooting
265+
266+
### Deploy fails with "Queue does not exist"
267+
268+
The queue must be created before deploying. See [Step 1: Create a Queue](#1-create-a-queue).
269+
270+
### No notifications appearing
271+
272+
1. **Check the queue**: Dashboard → Queues → Your queue (are messages arriving?)
273+
2. **Check worker logs**: Dashboard → Workers → Your consumer worker → Logs
274+
3. **Verify subscription**: Dashboard → Queues → Your queue → Subscriptions tab
275+
276+
### "Invalid token" error in logs
277+
278+
- Verify `CLOUDFLARE_API_TOKEN` is set in worker settings
279+
- Ensure token has correct permissions (Edit Cloudflare Workers template)
280+
281+
### URLs not appearing
282+
283+
- **Preview URL missing**: Build was for main/master branch (shows Live URL instead)
284+
- **Live URL missing**: Check token has correct permissions
285+
286+
---
287+
288+
## Learn More
289+
290+
- [Queue Event Subscriptions](https://developers.cloudflare.com/queues/configuration/event-subscriptions/)
291+
- [Workers Builds](https://developers.cloudflare.com/workers/ci-cd/builds/)
292+
- [Cloudflare Queues](https://developers.cloudflare.com/queues/)

0 commit comments

Comments
 (0)