The best way to control Claude Code, Codex and more from any computer or phone

main
mdx 214 lines 6.75 KB
Raw
1 ---
2 title: React to GitHub events from a Worker
3 description: Subscribe a Cloudflare Worker to GitHub repository webhooks with typed payloads — alchemy provisions the webhook and verifies delivery signatures.
4 sidebar:
5 order: 20
6 ---
7
8 A push lands on `main`, a pull request opens, a release tag appears —
9 and you want code to run. `GitHub.consumeRepositoryEvents` subscribes
10 a Cloudflare Worker to a repository's webhooks: alchemy provisions
11 the webhook on the repo, points it at the Worker, verifies each
12 delivery's signature, and hands your handler a fully typed payload.
13
14 This event source is **Cloudflare-only today** — see
15 [the note below](#cloudflare-only-today).
16
17 ## 1. Subscribe to push events
18
19 Call `consumeRepositoryEvents` in the Worker's Construction phase with the
20 repository and the events you want, plus a handler that runs once per
21 delivery:
22
23 ```typescript
24 // src/worker.ts
25 import * as Cloudflare from "@alchemy.run/cloudflare";
26 import * as GitHub from "@alchemy.run/github";
27 import * as Effect from "effect/Effect";
28 import * as HttpServerResponse from "effect/http/HttpServerResponse";
29
30 export default Cloudflare.Worker(
31 "Worker",
32 { main: import.meta.url },
33 Effect.gen(function* () {
34 yield* GitHub.consumeRepositoryEvents(
35 {
36 owner: "my-org",
37 repository: "my-repo",
38 events: ["push"],
39 },
40 (event) => Effect.log(`received ${event.name} (${event.id})`),
41 );
42
43 return {
44 fetch: Effect.gen(function* () {
45 return HttpServerResponse.text("ok");
46 }),
47 };
48 }),
49 );
50 ```
51
52 `events` defaults to `["push"]`; pass `["*"]` to receive everything
53 GitHub emits. The handler receives each delivery as a typed
54 `WebhookEvent` and returns an `Effect` — more on the payload types
55 below.
56
57 ## 2. Provide the Cloudflare runtime layer
58
59 `consumeRepositoryEvents` is host-agnostic — it requires a
60 `RepositoryEventSource` implementation. Provide the Cloudflare one on
61 the Worker:
62
63 ```diff lang="typescript"
64 export default Cloudflare.Worker(
65 "Worker",
66 { main: import.meta.url },
67 Effect.gen(function* () {
68 // ...
69 - }),
70 + }).pipe(Effect.provide(GitHub.RepositoryEventSourceLive)),
71 );
72 ```
73
74 `GitHub.RepositoryEventSourceLive` does both halves: at deploy time it
75 provisions the repository webhook pointing at this Worker, and at
76 runtime it registers a `fetch` listener that claims the webhook's
77 delivery path and forwards each verified delivery to your handler.
78 Requests on any other path fall through to the Worker's own `fetch`.
79
80 ## 3. Add GitHub providers to the Stack
81
82 The webhook is a GitHub resource, so the Stack needs GitHub providers
83 alongside Cloudflare's:
84
85 ```typescript
86 // alchemy.run.ts
87 import * as Alchemy from "alchemy";
88 import * as Cloudflare from "@alchemy.run/cloudflare";
89 import * as GitHub from "@alchemy.run/github";
90 import * as Effect from "effect/Effect";
91 import * as Layer from "effect/Layer";
92 import Worker from "./src/worker.ts";
93
94 export default Alchemy.Stack(
95 "GitHubEvents",
96 {
97 providers: Layer.mergeAll(Cloudflare.providers(), GitHub.providers()),
98 state: Cloudflare.state(),
99 },
100 Effect.gen(function* () {
101 const worker = yield* Worker;
102 return { url: worker.url.as<string>() };
103 }),
104 );
105 ```
106
107 `GitHub.providers()` resolves credentials from the environment, a
108 stored PAT, or the `gh` CLI — see [GitHub setup](/github/setup). The
109 token needs `repo` scope (admin access to the repository) to manage
110 webhooks.
111
112 ## 4. Verify deliveries with a secret
113
114 Without a secret, anyone who learns the delivery URL can forge
115 events. Pass one and alchemy rejects any delivery whose
116 `X-Hub-Signature-256` header doesn't match:
117
118 ```diff lang="typescript"
119 +import * as Config from "effect/Config";
120
121 Effect.gen(function* () {
122 + const secret = yield* Config.Redacted("GITHUB_WEBHOOK_SECRET");
123 +
124 yield* GitHub.consumeRepositoryEvents(
125 {
126 owner: "my-org",
127 repository: "my-repo",
128 events: ["push"],
129 + secret,
130 },
131 (event) => Effect.log(`received ${event.name} (${event.id})`),
132 );
133 ```
134
135 The webhook is provisioned with the secret, so GitHub signs every
136 delivery with `HMAC-SHA256`; the Worker recomputes the signature over
137 the raw body and compares in constant time, answering `401` on a
138 mismatch. `Config.Redacted` reads the value from your `.env` at
139 deploy time and binds it as a Worker secret — see
140 [Secrets & env](/cloudflare/security/secrets-env).
141
142 ## 5. Deploy
143
144 ```sh
145 alchemy deploy
146 ```
147
148 On deploy, alchemy creates a `GitHub.Webhook` on the repository whose
149 delivery URL is the Worker's URL plus a deterministic per-repo path
150 (`/__alchemy/github/{owner}/{repository}` — override with the `path`
151 prop). The webhook is updated in place on subsequent deploys and
152 deleted when the stack is destroyed. Push a commit and watch the
153 handler log the delivery.
154
155 ## What alchemy automates
156
157 One `consumeRepositoryEvents` call replaces the usual webhook
158 plumbing:
159
160 - **Provisioning** — a [`GitHub.Webhook`](/providers/github/webhook)
161 resource is created on the repo, wired to the Worker's URL. You
162 never paste a URL into repo settings.
163 - **Secret distribution** — the signing secret is bound onto the
164 Worker as a secret under a deterministic env name; the runtime
165 reads it back to verify signatures.
166 - **Routing** — the runtime only claims `POST`s on the delivery
167 path (`405` for other methods, `202` once a delivery is accepted);
168 every other request reaches your own `fetch` handler untouched.
169 - **Signature verification** — `HMAC-SHA256` over the raw body,
170 compared in constant time against `X-Hub-Signature-256`.
171
172 ## Typed payloads
173
174 `event` is a discriminated union of
175 `{ id, name, payload }` keyed on `name`, narrowed to the events you
176 selected. A `switch` on `event.name` narrows `payload` exhaustively:
177
178 ```typescript
179 yield* GitHub.consumeRepositoryEvents(
180 {
181 owner: "my-org",
182 repository: "my-repo",
183 events: ["push", "pull_request"],
184 },
185 (event) => {
186 switch (event.name) {
187 case "push":
188 return Effect.log(`push to ${event.payload.ref}`);
189 case "pull_request":
190 return Effect.log(`PR: ${event.payload.pull_request.title}`);
191 }
192 },
193 );
194 ```
195
196 Selecting `["*"]` (or omitting `events`) widens the union back to
197 every GitHub event name.
198
199 ## Cloudflare-only today
200
201 `GitHub.RepositoryEventSourceLive` runs on any host that is a
202 `WebhookHost`, and today only Cloudflare Workers are. On other hosts you can still
203 provision a [`GitHub.Webhook`](/providers/github/webhook) directly
204 with any delivery URL, but signature verification and routing are
205 yours to implement.
206
207 ## Where next
208
209 - [GitHub provider](/github) — repositories, Actions secrets and
210 variables, and the rest of the CI/CD glue.
211 - [Workers](/cloudflare/compute/workers) — the host this event source runs
212 on.
213 - [Webhook API reference](/providers/github/webhook) — the resource
214 provisioned under the hood.