deployment

107 notes in this subject, read out of this brain and free to use. This is page 1 of 2.

Deploy to Cloudflare button functionality

Deploy to Cloudflare buttons enable: cloning a Git repository into the user's GitHub/GitLab account, configuring project details like repository name and Worker name, and automatically building and deploying using Workers Builds with automatic resource provisioning.

Automatically provisioned resources via Deploy to Cloudflare

The following Cloudflare resources are automatically provisioned during Deploy to Cloudflare deployment: KV namespaces, D1 databases, R2 buckets, Hyperdrive, Vectorize databases, Secrets Store Secrets, Durable Objects, Workers AI, and Queues.

Wrangler configuration requirements for Deploy to Cloudflare

The source repository must include a Wrangler configuration file with default values for resource names, resource IDs, and other properties for each binding. Cloudflare reads this configuration to determine resource requirements and provisions necessary resources during deployment, updating the configuration with newly created resource IDs and namespace IDs.

Define environment variables for Deploy to Cloudflare

Worker environment variables can be defined in the Wrangler configuration file using the "vars" field with key-value pairs. Example: {"vars": {"API_HOST": "https://example.com"}}.

Deploy to Cloudflare button embed HTML

To embed a Deploy to Cloudflare button in HTML, use: <a href="https://deploy.workers.cloudflare.com/?url=<YOUR_REPO_URL>"><img src="https://deploy.workers.cloudflare.com/button" alt="Deploy to Cloudflare"/></a>. Replace <YOUR_REPO_URL> with your project's repository URL.

Define secrets for Deploy to Cloudflare

Worker secrets can be defined in a .dev.vars.example or .env.example file using dotenv format. Secrets Store secrets can be configured in the Wrangler configuration file using the "secrets_store_secrets" field with binding, store_id, and secret_name properties.

Deploy to Cloudflare button embed markdown

To embed a Deploy to Cloudflare button in markdown, use: [![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=<your git repo URL>). Replace <your git repo URL> with your project's repository URL. You can optionally specify a subdirectory in the URL.

Auto-detection of build and deploy scripts in Deploy to Cloudflare

If custom build and deploy scripts exist in package.json, Cloudflare automatically detects and pre-populates the build and deploy fields during deployment configuration. Users can modify or accept these. If no deploy script is specified, npx wrangler deploy is preconfigured by default. If no build script is specified, the field is left blank.

Running D1 migrations with Deploy to Cloudflare

To run D1 migrations as part of deployment, specify the migration command in your package.json deploy script. Use the binding name rather than the database name in migration commands to ensure success when users specify a different database name. Example: "deploy": "npm run db:migrations:apply && wrangler deploy" and "db:migrations:apply": "wrangler d1 migrations apply DB_BINDING --remote".

Provide descriptions for bindings in Deploy to Cloudflare

Descriptions for bindings can be provided in package.json under "cloudflare.bindings" to help users understand why bindings are required and how to configure them. Descriptions support inline markdown including code, bold, italics, and links.

Deploy to Cloudflare button limitation: monorepos

Deploy to Cloudflare does not fully support monorepos. If a repository URL contains a subdirectory, the application must be fully isolated within that subdirectory including dependencies, as Cloudflare treats it as the root. Multiple Workers applications in a monorepo cannot be deployed together; each requires a separate Deploy button and will create distinct Workers applications.

Deploy to Cloudflare button limitation: repository type

Deploy to Cloudflare buttons only support public repositories from github.com or gitlab.com. Source repositories from other platforms or self-hosted versions of GitHub and GitLab are not supported. Private repositories cannot be deployed via Deploy to Cloudflare buttons.

Deploy to Cloudflare button limitation: application type

Deploy to Cloudflare buttons only support Workers applications. Pages applications are not supported.

Generate Deploy to Cloudflare button from dashboard

If you have already deployed your application using Workers Builds, you can generate a Deploy to Cloudflare button directly from the Cloudflare dashboard by selecting the share button within your Worker details and copying the provided snippet.

Deploying from the Playground

Workers can be deployed directly from the Playground. If already logged in, the Worker can be reviewed before deploying. Otherwise, the user is taken through a first-time user onboarding flow before review and deployment. Once deployed, the Worker gets a unique URL and is available almost instantly on Cloudflare's global network.

Gradual deployments available with ES modules

You can gradually deploy changes to your Worker when you use the ES modules format.

wrangler deploy builds and deploys projects

Run `npx wrangler deploy` to build and deploy your project. Projects can be deployed to a *.workers.dev subdomain or a Custom Domain from your own machine or from any CI/CD system, including Cloudflare's own.

GitHub integration for Worker deployment

When connecting a GitHub project to Cloudflare Workers via the Connect a new Worker guide, ensure the build command matches the command found in Netlify, and the deploy command should be the default 'npx wrangler deploy'.

Connect Vercel project to Cloudflare Workers

Use the Connect a new Worker guide to connect your GitHub project to Cloudflare Workers. In the configuration step, ensure your build command is the same as the command found in Vercel. The deploy command should be the default: npx wrangler deploy.

Cloudflare Documentation MCP server for Workers assistance

The Cloudflare Documentation MCP server can be used in coding assistants to provide better context when building with Workers. It includes the Pages-to-Workers migration prompt when asked to migrate from Pages to Workers.

Migrate from Pages CI/CD to Workers Builds

To migrate from Pages' built-in CI/CD system to Workers Builds, first connect the repository to Workers Builds, then disable automatic deployments on the Pages project.

Workers preview URLs configuration for staging environments

To get a similar preview environment experience as Pages in Workers, ensure preview URLs are enabled (they are on by default) and enable non-production branch builds in Workers Builds. Preview URLs can be optionally protected with Cloudflare Access.

Delete Pages project after migration

Once a Pages project has been successfully migrated to Workers and all production traffic has been moved, the Pages project can be deleted in the Cloudflare dashboard or using the command: wrangler pages project delete.

AI coding assistant migration prompt for Pages to Workers

An experimental prompt is available for AI coding assistants (e.g., Claude Code, Cursor) to help migrate Pages projects to Workers. The prompt is located at: https://developers.cloudflare.com/workers/prompts/pages-to-workers.txt

Workers Builds non-production branch configuration

Workers Builds supports enabling non-production branch builds, though does not yet have the same level of configurability as Pages branch build controls.

Deploy Workers with wrangler

To deploy a Cloudflare Workers application, run: npx wrangler deploy. This command builds and deploys your code to Cloudflare.

Deploy Slackbot with wrangler

Deploy the completed Slackbot application using npm run deploy (or the equivalent based on the package manager used). Wrangler handles bundling, uploading, and releasing the code to Cloudflare Workers. After deployment, the GitHub webhook and Slack slash commands will route to the deployed application.

Delete deployed Worker with wrangler delete

Run 'npx wrangler delete <WORKER_NAME>' to delete a deployed Worker. This removes the Worker from the Cloudflare global network.

Deploy application with npx wrangler deploy

Run npx wrangler deploy to deploy a Cloudflare Workers application. The application will be deployed to the *.workers.dev subdomain by default.

Authenticate Wrangler with npx wrangler login

Before deploying a Cloudflare Workers application, authenticate Wrangler by running npx wrangler login.

Deploy Worker with wrangler deploy

Run `npx wrangler deploy` to deploy your Worker project. This publishes the worker to Cloudflare's infrastructure and generates a deployment URL that can be used for webhooks or other integrations.

Deploy OpenAI Worker with Wrangler

Deploy a Worker application with the OpenAI integration by running npx wrangler deploy. The Worker will be accessible at https://<WORKER_NAME>.<SUBDOMAIN>.workers.dev. Query parameters can be passed in the URL to customize requests, for example ?message=<custom_message>.

Deploy Worker after development

After developing and testing a Worker locally, deploy it using npm run deploy.

Deploy Worker application with Wrangler

To deploy a Worker application to Cloudflare, run `npx wrangler deploy` from the Worker application directory. The application becomes accessible at `<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev`.

Deploy Prisma Postgres Worker application

Deploy a Worker project with Prisma to Cloudflare using: npm run deploy. The wrangler CLI will bundle and upload the application. If not already logged in, a browser window opens to prompt login to the Cloudflare dashboard.

Deploy DATABASE_URL secret to Cloudflare Workers

To make DATABASE_URL available in production, use: npx wrangler secret put DATABASE_URL, then paste the DATABASE_URL value from .dev.vars when prompted. Wrangler will ask to create a new Worker if one doesn't exist.

Verify Prisma Postgres Worker deployment

After deployment completes, verify the application by visiting the live URL provided in deployment output (format: https://{PROJECT_NAME}.workers.dev). Ensure secrets were added correctly and check deployment logs for errors if issues occur.

Deploy Rust Worker

Deploy a Rust Worker to Cloudflare by running 'npx wrangler deploy' from the project directory.

Default deployment behavior with wrangler deploy

By default, when you use `wrangler deploy`, Workers Builds, or the Workers Script Upload API, a new version is created and immediately deployed to 100% of traffic.

Upload version without deploying via wrangler versions upload

Use the `wrangler versions upload` command to upload a new version without deploying it. This separates uploading and deployment into independent actions. Versions before 3.73.0 require the `--x-versions` flag.

Upload version without deploying via dashboard

In the Cloudflare dashboard, go to Workers & Pages, select your Worker, click Edit code, make your changes, then select the down arrow next to Deploy and choose Save to upload without deploying.

Deploy uploaded version via wrangler versions deploy

Use the `wrangler versions deploy` command to create a deployment that routes traffic to an uploaded version. Follow interactive prompts to select the version and set traffic percentage. You can set traffic to less than 100% to start a gradual deployment.

Deploy uploaded version via dashboard

In the Cloudflare dashboard, go to Workers & Pages, select your Worker, click Deployments, then select Promote deployment and choose the version you want to deploy.

First upload requires wrangler deploy or C3

When creating a new Workers project for the first time, you must use C3 or `wrangler deploy`. Using `wrangler versions upload` the first time will fail.

Service worker syntax not supported for wrangler versions upload

Versions uploaded through `wrangler versions upload` must use ES modules format. Service worker syntax is not supported. Migrate to ES modules format before using versioned uploads.

Durable Object migrations must use wrangler deploy

Uploading a version that changes Durable Object class lifecycle is not supported through `wrangler versions upload`. Any change that creates, deletes, renames, or transfers a Durable Object class must be applied through `wrangler deploy`, including changes to the declarative `exports` field or legacy `migrations` array.

wrangler triggers deploy for Worker routing and cron triggers

To apply changes to a Worker's triggers (routes, domains, or cron triggers), use the `wrangler triggers deploy` command instead of `wrangler versions upload`.

Gradual deployments with Durable Objects have different behavior

Gradual deployments work differently for Durable Objects because only one version of each Durable Object can run at a time. Refer to the Gradual Deployments with Durable Objects documentation for details on version assignment, guarantees, and migrations.

Gradual deployments split traffic across Worker versions

Gradual deployments let you incrementally deploy new versions of a Worker by splitting traffic across versions. Instead of shifting all traffic to a new version at once, you can route a percentage of requests to the new version while the rest continue to be handled by the previous version.

Wrangler versions upload command creates new version without deploying

The wrangler versions upload command creates a new version of the Worker that is not automatically deployed. You must use wrangler versions deploy to actually split traffic between versions.

Wrangler minimum version for gradual deployments

Gradual deployments require Wrangler version 3.40.0 or later. Versions before 3.73.0 require you to specify a --x-versions flag.

Version skew definition and types

Version skew occurs when multiple versions of a Worker serve traffic simultaneously, causing clients and services to interact with more than one version in ways that produce errors or inconsistent behavior. Two types exist: version skew within a Worker (same user's consecutive requests handled by different versions) and version skew between Workers (one Worker calling another via service binding, where they are at different points in their gradual deployment).

Version affinity pins users to consistent version

By default, each request is independently routed to a version based on configured percentages, meaning consecutive requests from the same user can be handled by different versions. Version affinity can be used to pin a user to a consistent version for the duration of the gradual deployment.

Version overrides pin downstream Workers to specific version

Version overrides allow you to pin a downstream Worker to a specific version during a subrequest when one Worker calls another via a service binding, ensuring version compatibility during gradual deployments.

Testing gradual deployment with cURL loop

Example cURL command to test a split deployment by making 10 requests: for j in {1..10} do curl -s https://$WORKER_NAME.$SUBDOMAIN.workers.dev done Responses will vary depending on the percentages configured in the deployment. You can also target a specific version using version overrides.

Why Durable Object lifecycle changes are atomic operations

Durable Object lifecycle changes are atomic because gradual deployment of class deletion would create an error scenario. If a class deletion were applied to only 50% of Durable Object instances, then Workers requesting those deleted instances would fail. This scenario cannot be resolved through gradual rollout, making lifecycle changes necessarily atomic.

Only one version of each Durable Object can run at a time

To provide global uniqueness, only one version of each Durable Object can run at a time. This is why gradual deployments work differently for Durable Objects compared to regular Workers.

Gradual deployments with Durable Objects: version assignment

When you create a new gradual deployment for a Worker with Durable Objects, each Durable Object is assigned a Worker version based on the percentages configured in the deployment. This version assignment does not change until you create a new deployment.

Gradual deployments with Durable Objects: consistency guarantee

For a given deployment, requests to each Durable Object will always use the same Worker version. This ensures that a single Durable Object instance never changes versions mid-deployment.

Gradual deployments with Durable Objects: no revert guarantee

When you specify each version in the same order as the previous deployment and increase the percentage of a version, Durable Objects which were previously assigned that version will not be assigned a different version. This prevents reverting Durable Objects to an earlier version during gradual rollout.

Give your agent this brain