Skip to content
Cloudflare Docs
DirectoryAPISDKsChangelog

Gradual deployments

Gradual deployments let you incrementally deploy new versions of your 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.

Gradual Deployments

Using gradual deployments, you can:

  • Gradually shift traffic to a newer version of your Worker
  • Monitor error rates and exceptions across versions using observability tooling
  • Roll back to a previously stable version if you notice issues

Use gradual deployments

The following section guides you through an example usage of gradual deployments.

Via Wrangler

1. Create and deploy a new Worker

Create a new "Hello World" Worker using the create-cloudflare CLI (C3) and deploy it.

npm create cloudflare@latest -- <NAME> -- --type=hello-world

Answer yes or no to using TypeScript. Answer yes to deploying your application. This is the first version of your Worker.

2. Create a new version of the Worker

Edit the Worker code by changing the Response content and upload the Worker using the wrangler versions upload command.

npx wrangler versions upload

This will create a new version of the Worker that is not automatically deployed.

3. Create a new deployment

Use the wrangler versions deploy command to create a new deployment that splits traffic between two versions. Follow the interactive prompts to select your desired percentages for each version.

npx wrangler versions deploy

4. Test the split deployment

Run a cURL command on your Worker to test the split deployment.

Terminal window
for j in {1..10}
do
    curl -s https://$WORKER_NAME.$SUBDOMAIN.workers.dev
done

You should see 10 responses. Responses will vary depending on the percentages configured in step #3.

You can also target a specific version using version overrides.

5. Set your new version to 100% deployment

Run wrangler versions deploy again and follow the interactive prompts. Select the new version and set it to 100%.

npx wrangler versions deploy

Via the Cloudflare dashboard

  1. In the Cloudflare dashboard, go to the Workers & Pages page.

    Go to Workers & Pages

  2. Select Create application > Hello World template > deploy your Worker.

  3. Once the Worker is deployed, go to the online code editor through Edit code. Edit the Worker code (change the Response content).

  4. To save changes without deploying, select the down arrow next to Deploy > Save. This will create a new version of your Worker.

  5. Go to Deployments and select Promote deployment to create a split between the two versions.

Version skew

Because gradual deployments mean multiple versions of your Worker serve traffic simultaneously, clients and services can end up interacting with more than one version in ways that produce errors or inconsistent behavior. This is called version skew.

Version skew within a Worker

By default, each request is independently routed to a version based on the configured percentages. This means consecutive requests from the same user - including page reloads and asset fetches - can be handled by different versions.

If you want to pin a user to a consistent version for the duration of the gradual deployment, you can use version affinity.

Version skew between Workers

When one Worker calls another via a service binding, the two Workers may be at different points in their own gradual deployment. Worker A (on its new version) might call Worker B, but the request lands on Worker B's old version where the API contract is different.

You can use version overrides to pin a downstream Worker to a specific version during a subrequest.

Durable Objects

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

Observability

When using gradual deployments, you may want to attribute Workers invocations to a specific version in order to get visibility into the impact of deploying new versions.

Logpush

A new ScriptVersion object is available in Workers Logpush. ScriptVersion can only be added through the Logpush API right now. Sample API call:

Terminal window
curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/logpush/jobs' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
"name": "workers-logpush",
"output_options": {
    "field_names": ["Event", "EventTimestampMs", "Outcome", "Logs", "ScriptName", "ScriptVersion"]
},
"destination_conf": "<DESTINATION_URL>",
"dataset": "workers_trace_events",
"enabled": true
}'| jq .

ScriptVersion is an object with the following structure:

{
  "ScriptVersion": {
    "id": "<UUID>",
    "message": "<MESSAGE>",
    "tag": "<TAG>"
  }
}

Runtime binding

Use the Version metadata binding to access version ID or version tag in your Worker.

Limits

Deployments limit

You can only create a gradual deployment with the last 100 uploaded versions of your Worker.