Continuous Integration

Set up preview deployments and continuous integration for your Alchemy projects using GitHub Actions.

As part of this guide, we’ll:

Add a Github Workflow to deploy your prod stage from the main branch
Deploy a preview pr-<number> stage for each Pull Request
Update your alchemy.run.ts script to add a Github Comment to the PR with the preview URL

Configure environment variables

Set up required secrets in your GitHub repository settings (Settings → Secrets and variables → Actions):
Terminal window
```
ALCHEMY_PASSWORD=your-encryption-password
ALCHEMY_STATE_TOKEN=your-state-token
CLOUDFLARE_API_TOKEN=your-cloudflare-api-token
CLOUDFLARE_EMAIL=your-cloudflare-email
```
Tip
1. See the Cloudflare Auth Guide if you don’t have a CLOUDFLARE_API_TOKEN
2. See the Cloudflare State Store Guide if you don’t have a ALCHEMY_STATE_TOKEN

Set up preview environments in your Alchemy script

Update your alchemy.run.ts to support multiple stages, use the CloudflareStateStore and add a GithubComment to the PR with the preview URL:

import alchemy from "alchemy";
import { Worker, Vite } from "alchemy/cloudflare";
import { GitHubComment } from "alchemy/github";
import { CloudflareStateStore } from "alchemy/state";

const app = await alchemy("my-app", {
  stateStore: (scope) => new CloudflareStateStore(scope),
});

// your website may be different, we use Vite for illustration purposes
const website = await Vite("website");

console.log(`🚀 Deployed to: https://${website.url}`);

if (process.env.PULL_REQUEST) {
  // if this is a PR, add a comment to the PR with the preview URL
  // it will auto-update with each push
  await GitHubComment("preview-comment", {
    owner: "your-username",
    repository: "your-repo",
    issueNumber: Number(process.env.PULL_REQUEST),
    body: `
     ## 🚀 Preview Deployed

     Your changes have been deployed to a preview environment:

     **🌐 Website:** ${website.url}

     Built from commit ${process.env.GITHUB_SHA?.slice(0, 7)}

     ---
     <sub>🤖 This comment updates automatically with each push.</sub>`,
  });
}

await app.finalize();

Create deployment workflow

Create .github/workflows/deploy.yml with a workflow for deploying your prod stage from the main branch and a preview pr-<number> stage for each Pull Request:

name: Deploy Application
on:
  push:
    branches:
      - main
  pull_request:
    types:
      - opened
      - reopened
      - synchronize
      - closed
concurrency:
  group: deploy-${{ github.ref }}
  cancel-in-progress: false
env:
  STAGE: ${{ github.ref == 'refs/heads/main' && 'prod' || format('pr-{0}',
    github.event.number) }}
jobs:
  deploy:
    if: ${{ github.event.action != 'closed' }}
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - name: Setup Bun
        uses: oven-sh/setup-bun@v2
      - name: Install dependencies
        run: bun install
      - name: Deploy
        run: bun alchemy deploy --stage ${{ env.STAGE }}
        env:
          ALCHEMY_PASSWORD: ${{ secrets.ALCHEMY_PASSWORD }}
          ALCHEMY_STATE_TOKEN: ${{ secrets.ALCHEMY_STATE_TOKEN }}
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          CLOUDFLARE_EMAIL: ${{ secrets.CLOUDFLARE_EMAIL }}
          PULL_REQUEST: ${{ github.event.number }}
          GITHUB_SHA: ${{ github.sha }}
  cleanup:
    runs-on: ubuntu-latest
    if: ${{ github.event.action == 'closed' && github.ref != 'refs/heads/main' }}
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4
      - name: Setup Bun
        uses: oven-sh/setup-bun@v2
      - name: Install dependencies
        run: bun install
      - name: Destroy Preview Environment
        run: bun alchemy destroy --stage ${{ env.STAGE }}
        env:
          ALCHEMY_PASSWORD: ${{ secrets.ALCHEMY_PASSWORD }}
          ALCHEMY_STATE_TOKEN: ${{ secrets.ALCHEMY_STATE_TOKEN }}
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          CLOUDFLARE_EMAIL: ${{ secrets.CLOUDFLARE_EMAIL }}
          PULL_REQUEST: ${{ github.event.number }}

name: Deploy Application
on:
  push:
    branches:
      - main
  pull_request:
    types:
      - opened
      - reopened
      - synchronize
      - closed
concurrency:
  group: deploy-${{ github.ref }}
  cancel-in-progress: false
env:
  STAGE: ${{ github.ref == 'refs/heads/main' && 'prod' || format('pr-{0}',
    github.event.number) }}
jobs:
  deploy:
    if: ${{ github.event.action != 'closed' }}
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "24"
      - name: Install dependencies
        run: npm ci
      - name: Deploy
        run: npx alchemy deploy --stage ${{ env.STAGE }}
        env:
          ALCHEMY_PASSWORD: ${{ secrets.ALCHEMY_PASSWORD }}
          ALCHEMY_STATE_TOKEN: ${{ secrets.ALCHEMY_STATE_TOKEN }}
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          CLOUDFLARE_EMAIL: ${{ secrets.CLOUDFLARE_EMAIL }}
          PULL_REQUEST: ${{ github.event.number }}
          GITHUB_SHA: ${{ github.sha }}
  cleanup:
    runs-on: ubuntu-latest
    if: ${{ github.event.action == 'closed' && github.ref != 'refs/heads/main' }}
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "24"
      - name: Install dependencies
        run: npm ci
      - name: Destroy Preview Environment
        run: npx alchemy destroy --stage ${{ env.STAGE }}
        env:
          ALCHEMY_PASSWORD: ${{ secrets.ALCHEMY_PASSWORD }}
          ALCHEMY_STATE_TOKEN: ${{ secrets.ALCHEMY_STATE_TOKEN }}
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          CLOUDFLARE_EMAIL: ${{ secrets.CLOUDFLARE_EMAIL }}
          PULL_REQUEST: ${{ github.event.number }}

name: Deploy Application
on:
  push:
    branches:
      - main
  pull_request:
    types:
      - opened
      - reopened
      - synchronize
      - closed
concurrency:
  group: deploy-${{ github.ref }}
  cancel-in-progress: false
env:
  STAGE: ${{ github.ref == 'refs/heads/main' && 'prod' || format('pr-{0}',
    github.event.number) }}
jobs:
  deploy:
    if: ${{ github.event.action != 'closed' }}
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - name: Setup pnpm
        uses: pnpm/action-setup@v4
        with:
          version: "10"
          run_install: false
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "24"
          cache: pnpm
      - name: Install dependencies
        run: pnpm install
      - name: Deploy
        run: pnpm dlx alchemy deploy --stage ${{ env.STAGE }}
        env:
          ALCHEMY_PASSWORD: ${{ secrets.ALCHEMY_PASSWORD }}
          ALCHEMY_STATE_TOKEN: ${{ secrets.ALCHEMY_STATE_TOKEN }}
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          CLOUDFLARE_EMAIL: ${{ secrets.CLOUDFLARE_EMAIL }}
          PULL_REQUEST: ${{ github.event.number }}
          GITHUB_SHA: ${{ github.sha }}
  cleanup:
    runs-on: ubuntu-latest
    if: ${{ github.event.action == 'closed' && github.ref != 'refs/heads/main' }}
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4
      - name: Setup pnpm
        uses: pnpm/action-setup@v4
        with:
          version: "10"
          run_install: false
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "24"
          cache: pnpm
      - name: Install dependencies
        run: pnpm install
      - name: Destroy Preview Environment
        run: pnpm dlx alchemy destroy --stage ${{ env.STAGE }}
        env:
          ALCHEMY_PASSWORD: ${{ secrets.ALCHEMY_PASSWORD }}
          ALCHEMY_STATE_TOKEN: ${{ secrets.ALCHEMY_STATE_TOKEN }}
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          CLOUDFLARE_EMAIL: ${{ secrets.CLOUDFLARE_EMAIL }}
          PULL_REQUEST: ${{ github.event.number }}

name: Deploy Application
on:
  push:
    branches:
      - main
  pull_request:
    types:
      - opened
      - reopened
      - synchronize
      - closed
concurrency:
  group: deploy-${{ github.ref }}
  cancel-in-progress: false
env:
  STAGE: ${{ github.ref == 'refs/heads/main' && 'prod' || format('pr-{0}',
    github.event.number) }}
jobs:
  deploy:
    if: ${{ github.event.action != 'closed' }}
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "24"
          cache: yarn
      - name: Install yarn
        run: npm install -g yarn
      - name: Install dependencies
        run: yarn install
      - name: Deploy
        run: yarn dlx alchemy deploy --stage ${{ env.STAGE }}
        env:
          ALCHEMY_PASSWORD: ${{ secrets.ALCHEMY_PASSWORD }}
          ALCHEMY_STATE_TOKEN: ${{ secrets.ALCHEMY_STATE_TOKEN }}
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          CLOUDFLARE_EMAIL: ${{ secrets.CLOUDFLARE_EMAIL }}
          PULL_REQUEST: ${{ github.event.number }}
          GITHUB_SHA: ${{ github.sha }}
  cleanup:
    runs-on: ubuntu-latest
    if: ${{ github.event.action == 'closed' && github.ref != 'refs/heads/main' }}
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "24"
          cache: yarn
      - name: Install yarn
        run: npm install -g yarn
      - name: Install dependencies
        run: yarn install
      - name: Destroy Preview Environment
        run: yarn dlx alchemy destroy --stage ${{ env.STAGE }}
        env:
          ALCHEMY_PASSWORD: ${{ secrets.ALCHEMY_PASSWORD }}
          ALCHEMY_STATE_TOKEN: ${{ secrets.ALCHEMY_STATE_TOKEN }}
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          CLOUDFLARE_EMAIL: ${{ secrets.CLOUDFLARE_EMAIL }}
          PULL_REQUEST: ${{ github.event.number }}