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.

​​ 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 Open API docs link 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

To create a new version of your Worker that is not deployed immediately, use the wrangler versions upload --experimental-versions 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 --experimental-versions command or via the Cloudflare dashboard under the Deployments tab.

​​ 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 Open external link 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 --experimental-versions 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 --experimental-versions. 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.

​​ Smart Placement

Smart Placement is not supported for versions that are uploaded through [wrangler versions upload --experimental-versions]. You must use wrangler deploy if you have Smart Placement enabled on a Worker.

Smart Placement support for versions will be coming in the near future.

​​ mTLS bindings

mTLS bindings are not supported for versions that are uploaded through wrangler versions upload --experimental-versions. You must use wrangler deploy if you configured mTLS bindings in your Worker.

mTLS bindings support for versions will be coming in the near future.