Deploy to Cloudflare Workers

Deploy to Cloudflare Workers

reddit [#143] Created with Sketch.
Joe Klakus
Joe Klakus
1 min read

Introduction:

Cloudflare Workers is a powerful edge computing platform that allows you to deploy applications closer to users worldwide. When combined with GitHub Actions, you can create a robust CI/CD pipeline that automatically builds and deploys your Astro application on every push to the main branch. In this tutorial, we’ll walk through setting up a complete deployment workflow to Cloudflare Workers.

Why Use GitHub Actions for Cloudflare Deployment?

Cloudflare’s dashboard has a 20-minute build limit when deploying projects directly through their web interface. For large or complex Astro projects, this can be insufficient, causing deployments to fail mid-build.

By using GitHub Actions, you bypass this limitation entirely:

  • GitHub Actions provides a 6-hour timeout for workflows
  • You get access to powerful caching strategies for dependencies and build artifacts
  • Automated builds on every commit without manual intervention
  • Full control over the build environment and configuration

This approach ensures your project builds successfully regardless of complexity or size.

Prerequisites

Before we begin, make sure you have:

  • A Cloudflare account
  • An existing Astro project
  • A GitHub repository connected to your project
  • Cloudflare Account ID and API Token

Step 1: Set Up Cloudflare Configuration

First, create a wrangler.jsonc configuration file in your project’s root directory. This file will define your Cloudflare Worker settings:

{
  "name": "my-astro-app",
  "compatibility_date": "2026-01-10",
  "assets": {
    "directory": "./dist"
  }
}

Step 2: Configure GitHub Secrets

Navigate to your GitHub repository settings and add the following secrets:

  • CLOUDFLARE_ACCOUNT_ID: Your Cloudflare account ID (found in Cloudflare dashboard)
  • CLOUDFLARE_API_TOKEN: An API token with Workers deployment permissions

Step 3: Create GitHub Actions Workflow

Create a new file at .github/workflows/deploy.yml with the following configuration:

on:
  push:
    branches:
      - main
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Setup pnpm
        uses: pnpm/action-setup@v4
        with:
          version: 9

      - name: Get pnpm store directory
        id: pnpm-cache
        shell: bash
        run: |
          echo "STORE_PATH=$(pnpm store path)" >> $GITHUB_OUTPUT

      - name: Setup pnpm cache
        uses: actions/cache@v4
        with:
          path: ${{ steps.pnpm-cache.outputs.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Cache Astro build
        uses: actions/cache@v4
        with:
          path: |
            node_modules/.astro
          key: ${{ runner.os }}-astro-${{ hashFiles('**/pnpm-lock.yaml') }}-${{ hashFiles('**/astro.config.*') }}
          restore-keys: |
            ${{ runner.os }}-astro-${{ hashFiles('**/pnpm-lock.yaml') }}-
            ${{ runner.os }}-astro-

      - name: Build project
        run: pnpm build

      - name: Deploy to Cloudflare Workers
        run: pnpm exec wrangler deploy
        env:
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}

Step 4: Workflow Breakdown

Let’s understand each part of the workflow:

Triggers:

  • on.push.branches.main: Automatically runs on pushes to the main branch
  • workflow_dispatch: Allows manual triggering from the GitHub Actions UI

Setup Steps:

  1. Checkout code: Retrieves your repository code
  2. Setup Node.js: Configures Node.js v20
  3. Setup pnpm: Installs pnpm package manager version 9
  4. pnpm cache: Stores pnpm packages to speed up future builds
  5. Install dependencies: Installs all project dependencies with frozen lockfile for consistency

Build Optimization:

  • Cache Astro build: Caches the .astro directory for faster subsequent builds
  • Build project: Creates the production build of your Astro application

Deployment:

  • Uses Wrangler CLI to deploy the built project to Cloudflare Workers
  • Securely accesses Cloudflare credentials via GitHub Secrets

Step 5: Deploy Your Application

With the workflow in place, simply push your changes to the main branch:

git add .
git commit -m "Add Cloudflare Workers deployment"
git push origin main

GitHub Actions will automatically trigger the deployment workflow. You can monitor the progress in the “Actions” tab of your GitHub repository.

Step 6: Manual Deployment

If you need to deploy without pushing to main:

  1. Go to the “Actions” tab in your GitHub repository
  2. Select the “Deploy to Cloudflare Workers” workflow
  3. Click “Run workflow” button
  4. Select the branch and click “Run workflow”

Troubleshooting

Build Fails:

  • Check the workflow logs for specific errors
  • Ensure all dependencies are correctly specified in package.json
  • Verify that your project builds locally first

Deployment Fails:

  • Verify your Cloudflare credentials are correct
  • Check that your API token has the necessary permissions
  • Ensure the wrangler.jsonc configuration is valid

Cache Issues:

  • If experiencing cache-related problems, delete existing caches from GitHub Actions settings
  • The workflow will recreate caches on the next run

Best Practices

  1. Use Environment Variables: Store all sensitive data in GitHub Secrets, never commit them
  2. Lock Dependencies: Using --frozen-lockfile ensures consistent builds across deployments
  3. Monitor Deployments: Regularly check workflow logs for any issues
  4. Test Locally: Always test your build locally before pushing to trigger a deployment
  5. Version Control: Keep your workflow file version controlled for team collaboration

Conclusion

Deploying your Astro application to Cloudflare Workers via GitHub Actions creates a seamless automated pipeline. This setup ensures your application is always built consistently and deployed efficiently to Cloudflare’s global network. The combination of caching, automated triggers, and manual workflow dispatch provides flexibility while maintaining a robust deployment process.

With this workflow in place, you can focus on development while knowing your deployment process is reliable, secure, and automated.