How to Deploy Next.js 15 App to Cloudflare Workers with GitHub Actions: Complete CI/CD Guide

You can deploy a Next.js 15 application to Cloudflare Workers using a GitHub Actions workflow that runs tests, applies D1 database migrations, and deploys to preview, staging, or production environments based on the branch or pull request.

The ifindev/fullstack-next-cloudflare repository demonstrates a production-ready architecture for running Next.js 15 on Cloudflare's edge runtime. This guide explains how to implement a robust CI/CD pipeline using GitHub Actions to automate testing, database migrations, and multi-environment deployments.

Prerequisites and Repository Setup

Before implementing the deployment pipeline, ensure your Next.js 15 project is configured for the Cloudflare Workers runtime. The project must use the @opennextjs/cloudflare adapter to bridge Next.js server components with the Workers environment.

Key configuration files include:

• wrangler.jsonc: Defines D1, R2, and Workers AI bindings
• package.json: Contains deployment scripts like deploy and cf-typegen
• .github/workflows/deploy.yml: The CI/CD pipeline definition

Understanding the CI/CD Architecture

The deployment workflow in .github/workflows/deploy.yml consists of four specialized jobs that handle different stages of the release process.

The Test Job

The test job runs on every push and pull request to validate code quality before deployment. It executes type checking, linting, and the Next.js build process using pnpm. Only code that passes these checks proceeds to deployment.

Environment-Specific Deploy Jobs

Three deployment jobs handle different environments:

• deploy-preview: Creates temporary deployments for pull requests
• deploy-staging: Deploys the develop branch to a staging environment
• deploy-production: Deploys the main branch to production

Each job includes database backups, migration handling, and post-deployment health checks.

Configuring Cloudflare Resources and Secrets

The pipeline requires specific Cloudflare resources and GitHub Secrets to authenticate and configure the deployment.

Required GitHub Secrets

Store these sensitive values in your repository settings:

• CLOUDFLARE_API_TOKEN: Wrangler authentication token with Workers and D1 permissions
• CLOUDFLARE_ACCOUNT_ID: Your Cloudflare account identifier
• BETTER_AUTH_SECRET: HMAC secret for session signing
• GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET: OAuth credentials for authentication
• CLOUDFLARE_R2_URL: Public URL of your R2 bucket

Local Development Configuration

For local testing, create a .dev.vars file from the provided .dev.vars.example template. This file contains the same variables as the GitHub Secrets but is used by Wrangler during local development with pnpm run dev:cf.

The Deployment Workflow Explained

The GitHub Actions pipeline automates the entire release process from code push to live deployment.

Preview Deployments on Pull Requests

When developers open pull requests, the deploy-preview job automatically provisions a temporary environment. It generates TypeScript bindings with pnpm run cf-typegen, applies D1 migrations to the preview database, and deploys using pnpm run deploy --env preview. The workflow posts the preview URL directly to the pull request comments.

Staging and Production Pipelines

For the develop and main branches, the workflow executes additional safety measures. The deploy-staging job creates timestamped D1 backups before applying migrations, then deploys to the staging environment and performs a health check against /api/todos. The deploy-production job follows the same pattern with stricter pre-deployment checks and verification steps.

Database Migrations and Backups

Database schema changes are handled safely through Wrangler's D1 migration system. Before applying migrations to staging or production, the workflow executes backup commands to preserve the current database state. This allows for rapid rollback if deployment issues occur.

Manual Deployment Commands

While the GitHub Actions pipeline handles automated deployments, you can execute the same steps manually using the scripts defined in package.json:

# Install dependencies

pnpm install --frozen-lockfile

# Generate Cloudflare TypeScript bindings

pnpm run cf-typegen

# Apply migrations locally (optional)

pnpm run db:migrate:local

# Build for Cloudflare Workers

pnpm run build:cf

# Deploy to specific environment

pnpm run deploy --env preview
pnpm run deploy --env staging
pnpm run deploy  # production default

These commands utilize @opennextjs/cloudflare to package the Next.js application for the Workers runtime and Wrangler to handle resource bindings and deployment.

Summary

• The ifindev/fullstack-next-cloudflare repository provides a complete CI/CD pipeline for deploying Next.js 15 to Cloudflare Workers using GitHub Actions.
• The workflow in .github/workflows/deploy.yml handles testing, database migrations, backups, and multi-environment deployments (preview, staging, production).
• Required secrets include CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, and application-specific variables like BETTER_AUTH_SECRET and OAuth credentials.
• The @opennextjs/cloudflare adapter bridges Next.js server components with the Cloudflare Workers runtime, configured via wrangler.jsonc.

Frequently Asked Questions

What is the role of @opennextjs/cloudflare in this deployment setup?

The @opennextjs/cloudflare package acts as the bridge between Next.js 15 and the Cloudflare Workers runtime. It packages the Next.js application into a format compatible with Workers, handling server component rendering and API routes within the edge environment. This adapter is invoked through the pnpm run deploy command defined in package.json.

How does the workflow handle database migrations safely?

The GitHub Actions workflow applies D1 database migrations using Wrangler's migration system. For staging and production environments, it first creates timestamped backups of the existing database before applying any schema changes. This backup strategy allows for rapid rollback if the deployment encounters issues, ensuring data integrity throughout the CI/CD process.

Can I deploy to Cloudflare Workers without using GitHub Actions?

Yes, you can deploy manually using the command line tools provided in the repository. After installing dependencies with pnpm install, you can run pnpm run cf-typegen to generate TypeScript bindings, pnpm run build:cf to build the application, and pnpm run deploy --env [environment] to push directly to Cloudflare Workers. However, the GitHub Actions pipeline provides automated testing, migration safety, and multi-environment management that manual deployment lacks.

What triggers the different deployment environments?

The deployment environment is determined by the Git event type and branch name. Pull requests trigger the deploy-preview job to create temporary preview environments. Pushes to the develop branch trigger the deploy-staging job for pre-production testing. Pushes to the main branch trigger the deploy-production job for the live application. This branch-based strategy ensures that code progresses through testing stages before reaching production.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}