Versions & Deployments

Versions track changes to your Worker. Deployments configure how those changes are deployed to your traffic.

You can upload changes (versions) to your Worker independent of changing the version that is actively serving traffic (deployment).

Using versions and deployments is useful if:

• You are running critical applications on Workers and want to reduce risk when deploying new versions of your Worker using a rolling deployment strategy.
• You want to monitor for performance differences when deploying new versions of your Worker.
• You have a CI pipeline configured for Workers but want to cut manual releases.

Versions

A version is defined by the state of code as well as the state of configuration in a Worker’s wrangler.toml file. Versions track historical changes to bundled code and changes to configuration like bindings and compatibility date and compatibility flags over time.

Versions also track metadata associated with a version, including: the version ID, the user that created the version, deploy source, and timestamp. Optionally, a version message and version tag can be configured on version upload.

Note

State changes for associated Workers storage resources such as KV, R2, Durable Objects and D1 are not tracked with versions.

Deployments

Deployments track the version(s) of your Worker that are actively serving traffic. A deployment can consist of one or two versions of a Worker.

By default, Workers supports an all-at-once deployment model where traffic is immediately shifted from one version to the newly deployed version automatically. Alternatively, you can use gradual deployments to create a rolling deployment strategy.

You can also track metadata associated with a deployment, including: the user that created the deployment, deploy source, timestamp and the version(s) in the deployment. Optionally, you can configure a deployment message when you create a deployment.

Use versions and deployments

Create a new version

Review the different ways you can create versions of your Worker and deploy them.

Upload a new version and deploy it immediately

Changes uploaded with wrangler deploy, via the Cloudflare dashboard, or the Workers Script Upload API create a new version that is automatically deployed to 100% of traffic.

Upload a new version to be gradually deployed or deployed at a later time

Note

Wrangler versions before 3.73.0 require you to specify a --x-versions flag.

To create a new version of your Worker that is not deployed immediately, use the wrangler versions upload command or create a new version via the Cloudflare dashboard using the Save button. You can find the Save option under the down arrow beside the “Deploy” button.

Versions created in this way can then be deployed all at once or gradually deployed using the wrangler versions deploy command or via the Cloudflare dashboard under the Deployments tab.

Note

When using Wrangler, changes made to a Worker’s triggers routes, domains or cron triggers need to be applied with the command wrangler triggers deploy.

Note

New versions are not created when you make changes to resources connected to your Worker. For example, if two Workers (Worker A and Worker B) are connected via a service binding, changing the code of Worker B will not create a new version of Worker A. Changing the code of Worker B will only create a new version of Worker B. Changes to the service binding (such as, deleting the binding or updating the environment it points to) on Worker A will also not create a new version of Worker B.

View versions and deployments

Via Wrangler

Wrangler allows you to view the 10 most recent versions and deployments. Refer to the versions list and deployments documentation to view the commands.

Via the Cloudflare dashboard

To view your deployments in the Cloudflare dashboard:

1. Log in to the Cloudflare dashboard ↗ and select your account.
2. Go to Workers & Pages.
3. Select your Worker > Deployments.

Limits

First upload

You must use C3 or wrangler deploy the first time you create a new Workers project. Using wrangler versions upload the first time you upload a Worker will fail.

Service worker syntax

Service worker syntax is not supported for versions that are uploaded through wrangler versions upload. You must use ES modules format.

Refer to Migrate from Service Workers to ES modules to learn how to migrate your Workers from the service worker format to the ES modules format.

Durable Object migrations

Uploading a version with Durable Object migrations is not supported. Use wrangler deploy if you are applying a Durable Object migration.

This will be supported in the near future.