@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
mdx 497 lines 15.6 KB
Raw
1 ---
2 title: "Part 5: CI/CD"
3 description: Set up GitHub Actions for automated deployments, PR previews, and remote state — with Cloudflare credentials managed as code.
4 sidebar:
5 order: 5
6 ---
7
8 import { Steps, Tabs, TabItem } from "@astrojs/starlight/components";
9
10 In [Part 4](/cloudflare/tutorial/part-4) you ran your stack locally. Now you'll
11 hand it off to GitHub Actions: pushes to `main` deploy to production,
12 pull requests get isolated preview environments, and merged PRs clean
13 up after themselves.
14
15 The trick to doing this safely is **letting Alchemy provision its own
16 CI credentials**. Instead of pasting your personal Cloudflare API key
17 into GitHub, you'll write a small `stacks/github.ts` that mints a
18 scoped Cloudflare API token, then stores it as a GitHub Actions
19 secret — all from code, all checked in.
20
21 ## Confirm your state store is remote
22
23 CI needs to share state across runs, so a local `.alchemy/` directory
24 won't cut it. You already configured `Cloudflare.state()` back in
25 [Part 1](/cloudflare/tutorial/part-1#configure-state), which deploys a Worker
26 backed by a Durable Object with SQLite. Every deploy — local or
27 from CI — reads and writes state remotely through that Worker.
28
29 Double-check it's still wired up in `alchemy.run.ts`:
30
31 ```typescript
32 // alchemy.run.ts
33 export default Alchemy.Stack(
34 "MyApp",
35 {
36 providers: Cloudflare.providers(),
37 state: Cloudflare.state(),
38 },
39 // ...
40 );
41 ```
42
43 :::caution
44 If you're using `State.localState()` instead, switch it to
45 `Cloudflare.state()` (or another shared store) before continuing —
46 GitHub Actions runners can't see your local filesystem.
47 :::
48
49 ## Set up an `admin` profile
50
51 Your `alchemy.run.ts` only needs enough permission to deploy your
52 app. The `stacks/github.ts` you're about to write needs more: it
53 creates a brand-new Cloudflare API token, which requires the
54 `API Tokens > Write` permission.
55
56 Rather than hand those elevated rights to your day-to-day profile,
57 create a dedicated `admin` profile:
58
59 ```sh
60 alchemy profile create admin
61 alchemy profile edit --profile admin --add Cloudflare
62 ```
63
64 When asked for the Cloudflare authentication method, choose **API
65 Token or API Key**, not the recommended OAuth: Cloudflare's OAuth
66 scopes can't manage API tokens. Then pick one of:
67
68 - **API Key + Email** (the Global API Key) — has full account
69 access, including the ability to mint tokens.
70 - **API Token** — must be a token with at least
71 `User > API Tokens > Write` (for user-owned tokens) **and**
72 `Account > API Tokens > Write` (for the account whose tokens
73 you'll be creating). Most people use the Global API Key here
74 because the token-permissions UI in the Cloudflare dashboard is
75 fiddly.
76
77 :::danger[Heads up]
78 The credential stored under `--profile admin` can create new API
79 tokens with arbitrary scopes. Treat it like root. Do **not** use it
80 for everyday `alchemy deploy` runs against your application — keep
81 your default profile on a narrowly scoped API Token (or OAuth) and
82 only reach for `admin` when you're touching `stacks/github.ts`.
83 :::
84
85 You'll also be prompted for a GitHub credential. Pick `gh-cli` if
86 you have the GitHub CLI installed, otherwise paste a Personal
87 Access Token with the `repo` scope.
88
89 ## Scaffold the GitHub stack
90
91 Create `stacks/github.ts` with an empty stack that loads both
92 provider layers and reuses your remote state store. This is a
93 one-shot stack you'll deploy from your laptop (under the `admin`
94 profile) to provision the Cloudflare API token CI will use.
95
96 ```typescript
97 // stacks/github.ts
98 import * as Alchemy from "alchemy";
99 import * as Cloudflare from "@alchemy.run/cloudflare";
100 import * as GitHub from "@alchemy.run/github";
101 import * as Effect from "effect/Effect";
102 import * as Layer from "effect/Layer";
103 import * as Redacted from "effect/Redacted";
104
105 export default Alchemy.Stack(
106 "github",
107 {
108 providers: Layer.mergeAll(
109 Cloudflare.providers(),
110 GitHub.providers(),
111 ),
112 state: Cloudflare.state(),
113 },
114 Effect.gen(function* () {
115 const { accountId } = yield* yield* Cloudflare.CloudflareEnvironment;
116 }),
117 );
118 ```
119
120 `Cloudflare.CloudflareEnvironment` resolves the credentials of the
121 profile you're deploying with — here, the `admin` profile — and the
122 account ID comes along with them. You don't need to set a
123 `CLOUDFLARE_ACCOUNT_ID` environment variable; your login already
124 knows it.
125
126 Note the double `yield*`: the service's value is itself an Effect,
127 because credentials are cached and can refresh themselves (OAuth
128 tokens expire). The first `yield*` gets the service, the second
129 resolves the current credentials.
130
131 Reusing the same `Cloudflare.state()` you set up in Part 1 means the
132 token's ID is tracked alongside the rest of your infrastructure, so
133 any future edit (rename, policy change) produces a clean diff.
134
135 ## Mint a scoped Cloudflare API token
136
137 Add an `AccountApiToken` resource. Under the hood it calls
138 `POST /accounts/{account_id}/tokens` and returns the freshly minted
139 secret. Cloudflare only reveals that value once, so Alchemy stores it
140 in state — the raw token never touches your terminal.
141
142 ```diff lang="typescript"
143 Effect.gen(function* () {
144 const { accountId } = yield* yield* Cloudflare.CloudflareEnvironment;
145 +
146 + const apiToken = yield* Cloudflare.ApiToken.AccountApiToken("CIToken", {
147 + accountId,
148 + policies: [
149 + {
150 + effect: "allow",
151 + permissionGroups: [
152 + "Secrets Store Write",
153 + "Workers Scripts Write",
154 + "Workers KV Storage Write",
155 + "Workers R2 Storage Write",
156 + "D1 Write",
157 + "Queues Write",
158 + "Pages Write",
159 + "Account Settings Write",
160 + "Workers Tail Read",
161 + ],
162 + resources: {
163 + [`com.cloudflare.api.account.${accountId}`]: "*",
164 + },
165 + },
166 + ],
167 + });
168 }),
169 ```
170
171 The `permissionGroups` list scopes the token down to exactly what
172 your app needs. If you don't use D1 or R2, drop those entries.
173
174 ## Push the token into GitHub
175
176 Pipe `apiToken.value` straight into a `GitHub.Secret` so CI can read
177 it without the secret ever round-tripping through your shell.
178
179 ```diff lang="typescript"
180 });
181 +
182 + yield* GitHub.Secret("cf-api-token", {
183 + owner: "your-org",
184 + repository: "your-repo",
185 + name: "CLOUDFLARE_API_TOKEN",
186 + value: apiToken.value,
187 + });
188 }),
189 ```
190
191 Replace `your-org` and `your-repo` with your GitHub org and repo
192 slug.
193
194 ## Expose the account ID to CI
195
196 The workflow also needs `CLOUDFLARE_ACCOUNT_ID`. It isn't a secret in
197 the cryptographic sense, but storing it as a GitHub Actions secret
198 keeps all CI configuration in one place and out of your workflow YAML.
199
200 ```diff lang="typescript"
201 value: apiToken.value,
202 });
203 +
204 + yield* GitHub.Secret("cf-account-id", {
205 + owner: "your-org",
206 + repository: "your-repo",
207 + name: "CLOUDFLARE_ACCOUNT_ID",
208 + value: Redacted.make(accountId),
209 + });
210 }),
211 ```
212
213 `Redacted.make` wraps the plain string so it gets the same masking
214 treatment as the API token.
215
216 ## Deploy the GitHub stack
217
218 Run it once from your laptop, under the `admin` profile:
219
220 ```sh
221 alchemy deploy --config stacks/github.ts --profile admin
222 ```
223
224 You'll see Alchemy plan three creates — the Cloudflare token and the
225 two GitHub secrets — then apply them. When it's done, head to your repo's
226 **Settings → Secrets and variables → Actions** page; you should see
227 `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` listed there.
228
229 You only need to re-run this stack when you want to rotate the token
230 or change its permissions.
231
232 ## Create the workflow
233
234 Create `.github/workflows/deploy.yml`:
235
236 ```yaml
237 name: Deploy
238 on:
239 push:
240 branches: [main]
241 pull_request:
242 types: [opened, reopened, synchronize, closed]
243
244 concurrency:
245 group: deploy-${{ github.ref }}
246 cancel-in-progress: false
247
248 env:
249 STAGE: >-
250 ${{ github.event_name == 'pull_request'
251 && format('pr-{0}', github.event.number)
252 || (github.ref == 'refs/heads/main' && 'prod' || github.ref_name) }}
253
254 jobs:
255 deploy:
256 if: github.event.action != 'closed'
257 runs-on: ubuntu-latest
258 permissions:
259 contents: read
260 pull-requests: write
261 steps:
262 - uses: actions/checkout@v4
263 - uses: oven-sh/setup-bun@v2
264 - run: bun install
265 - name: Deploy
266 run: bun alchemy deploy --stage ${{ env.STAGE }} --yes
267 env:
268 CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
269 CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
270 PULL_REQUEST: ${{ github.event.number }}
271 GITHUB_SHA: ${{ github.sha }}
272 GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
273
274 cleanup:
275 if: github.event_name == 'pull_request' && github.event.action == 'closed'
276 runs-on: ubuntu-latest
277 permissions:
278 contents: read
279 pull-requests: write
280 steps:
281 - uses: actions/checkout@v4
282 - uses: oven-sh/setup-bun@v2
283 - run: bun install
284 - name: Safety Check
285 run: |
286 if [ "${{ env.STAGE }}" = "prod" ]; then
287 echo "ERROR: Cannot destroy prod environment in cleanup job"
288 exit 1
289 fi
290 - name: Destroy Preview
291 run: bun alchemy destroy --stage ${{ env.STAGE }} --yes
292 env:
293 CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
294 CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
295 PULL_REQUEST: ${{ github.event.number }}
296 ```
297
298 :::note[How STAGE is computed]
299
300 - Pull requests → `pr-{number}` (e.g. `pr-42`)
301 - Push to `main` → `prod`
302 - Other branches → the branch name
303
304 The cleanup job includes a safety check so `prod` can never be
305 accidentally destroyed.
306 :::
307
308 ## Add PR preview comments
309
310 Post the live URL as a comment on every PR. Update `alchemy.run.ts`:
311
312 ```diff lang="typescript"
313 // alchemy.run.ts
314 import * as Alchemy from "alchemy";
315 import * as Cloudflare from "@alchemy.run/cloudflare";
316 +import * as GitHub from "@alchemy.run/github";
317 +import * as Output from "alchemy/Output";
318 import * as Effect from "effect/Effect";
319 +import * as Layer from "effect/Layer";
320 import { Bucket } from "./src/bucket.ts";
321 import Worker from "./src/worker.ts";
322
323 export default Alchemy.Stack(
324 "MyApp",
325 {
326 - providers: Cloudflare.providers(),
327 + providers: Layer.mergeAll(
328 + Cloudflare.providers(),
329 + GitHub.providers(),
330 + ),
331 state: Cloudflare.state(),
332 },
333 Effect.gen(function* () {
334 const bucket = yield* Bucket;
335 const worker = yield* Worker;
336
337 + if (process.env.PULL_REQUEST) {
338 + yield* GitHub.Comment("preview-comment", {
339 + owner: "your-org",
340 + repository: "your-repo",
341 + issueNumber: Number(process.env.PULL_REQUEST),
342 + body: Output.interpolate`
343 + ## Preview Deployed
344 +
345 + **URL:** ${worker.url}
346 +
347 + Built from commit ${process.env.GITHUB_SHA?.slice(0, 7)}
348 +
349 + ---
350 + _This comment updates automatically with each push._
351 + `,
352 + });
353 + }
354
355 return {
356 bucketName: bucket.bucketName,
357 url: worker.url,
358 };
359 }),
360 );
361 ```
362
363 The logical ID `"preview-comment"` stays the same across pushes, so
364 Alchemy updates the existing comment instead of creating a new one.
365 `GITHUB_TOKEN` is provided automatically by Actions and authorizes
366 the comment.
367
368 ## The full picture
369
370 Here's how everything fits together:
371
372 1. You ran `stacks/github.ts` once under `--profile admin`. That
373 minted a scoped Cloudflare API token and pushed it into your
374 repo as a GitHub Actions secret.
375 2. A developer pushes a branch and opens a PR.
376 3. GitHub Actions checks out the code, installs deps, and runs
377 `alchemy deploy --stage pr-42` using the CI token.
378 4. Alchemy creates an isolated copy of every resource (bucket,
379 worker, etc.) under the `pr-42` stage and posts the preview URL
380 as a PR comment.
381 5. The reviewer clicks the URL and tests the preview.
382 6. The PR is merged — the cleanup job runs
383 `alchemy destroy --stage pr-42` and the preview infrastructure
384 disappears.
385 7. The push to `main` deploys `--stage prod`.
386
387 Each environment is fully isolated with its own bucket, worker, and
388 state.
389
390 ## Optional: separate test and prod Cloudflare accounts
391
392 If you want to keep preview environments on one Cloudflare account
393 and production on another, deploy two tokens from the same
394 `stacks/github.ts` and prefix the secrets accordingly.
395
396 Your profile resolves a single account ID, so this is the one case
397 where you pass the account IDs in explicitly — set
398 `TEST_CLOUDFLARE_ACCOUNT_ID` and `PROD_CLOUDFLARE_ACCOUNT_ID` in
399 your environment when deploying this stack.
400
401 ```typescript
402 // stacks/github.ts
403 import * as Alchemy from "alchemy";
404 import * as Cloudflare from "@alchemy.run/cloudflare";
405 import * as GitHub from "@alchemy.run/github";
406 import * as Config from "effect/Config";
407 import * as Effect from "effect/Effect";
408 import * as Layer from "effect/Layer";
409 import * as Redacted from "effect/Redacted";
410
411 export default Alchemy.Stack(
412 "github",
413 {
414 providers: Layer.mergeAll(
415 Cloudflare.providers(),
416 GitHub.providers(),
417 ),
418 state: Cloudflare.state(),
419 },
420 Effect.gen(function* () {
421 const testAccountId = yield* Config.String("TEST_CLOUDFLARE_ACCOUNT_ID");
422 const prodAccountId = yield* Config.String("PROD_CLOUDFLARE_ACCOUNT_ID");
423
424 const testToken = yield* Cloudflare.ApiToken.AccountApiToken("TestApiToken", {
425 accountId: testAccountId,
426 policies: [/* same policies as above */],
427 });
428
429 const prodToken = yield* Cloudflare.ApiToken.AccountApiToken("ProdApiToken", {
430 accountId: prodAccountId,
431 policies: [/* same policies as above */],
432 });
433
434 const secrets: Record<string, Redacted.Redacted<string>> = {
435 TEST_CLOUDFLARE_API_TOKEN: testToken.value,
436 TEST_CLOUDFLARE_ACCOUNT_ID: Redacted.make(testAccountId),
437 PROD_CLOUDFLARE_API_TOKEN: prodToken.value,
438 PROD_CLOUDFLARE_ACCOUNT_ID: Redacted.make(prodAccountId),
439 };
440
441 yield* Effect.all(
442 Object.entries(secrets).map(([name, value]) =>
443 GitHub.Secret(name, {
444 owner: "your-org",
445 repository: "your-repo",
446 name,
447 value,
448 }),
449 ),
450 );
451 }),
452 );
453 ```
454
455 In your workflow, choose which set of credentials to expose based
456 on `STAGE`:
457
458 ```yaml
459 env:
460 CLOUDFLARE_API_TOKEN: ${{ env.STAGE == 'prod' && secrets.PROD_CLOUDFLARE_API_TOKEN || secrets.TEST_CLOUDFLARE_API_TOKEN }}
461 CLOUDFLARE_ACCOUNT_ID: ${{ env.STAGE == 'prod' && secrets.PROD_CLOUDFLARE_ACCOUNT_ID || secrets.TEST_CLOUDFLARE_ACCOUNT_ID }}
462 ```
463
464 Your `admin` profile needs API-token-write permission on **both**
465 accounts. The simplest way is to log in with the Global API Key of
466 a user that's a member of both.
467
468 ## Recap
469
470 You now know how to:
471
472 - **Part 1** — Create a Stack and deploy a resource
473 - **Part 2** — Add a Worker with bindings to other resources
474 - **Part 3** — Write integration tests against deployed stacks
475 - **Part 4** — Run locally with `alchemy dev`
476 - **Part 5** — Mint scoped CI credentials with
477 `Cloudflare.ApiToken.AccountApiToken`, push them to GitHub with
478 `GitHub.Secret`, and deploy from Actions
479
480 In [Part 6](/cloudflare/tutorial/part-6), you'll ship the Worker's
481 traces and logs to Axiom — with the datasets and ingest token
482 declared in the same Stack as the Worker they observe.
483
484 ## What's next
485
486 - Go deeper on Cloudflare in the
487 [Cloudflare track](/cloudflare/compute/durable-objects) — layer
488 Durable Objects, hibernatable WebSockets, Containers, Workflows,
489 and Queues onto the Worker you built
490 - Read the [Resource Lifecycle](/infrastructure-as-code/resource-lifecycle)
491 guide for all CLI flags and options
492 - Explore the [CI guide](/environments/ci) for the AWS equivalents
493 (OIDC and access keys) and more workflow patterns
494 - Check out the [Testing a Stack](/testing/testing-a-stack) guide for
495 more advanced testing patterns
496 - Browse the [Providers](/providers) reference for all available
497 resources