The best way to control Claude Code, Codex and more from any computer or phone
| 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 |