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/CD pipeline configured for Workers but want to cut manual releases.
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, static assets 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 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.
Review the different ways you can create versions of your Worker and deploy them.
A new version that is automatically deployed to 100% of traffic when:
- Changes are uploaded with
wrangler deployvia the Cloudflare Dashboard - Changes are deployed with the command
npx wrangler deployvia Workers Builds - Changes are uploaded with the Workers Script Upload API
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.
Wrangler allows you to view the 10 most recent versions and deployments. Refer to the versions list and deployments documentation to view the commands.
To view your deployments in the Cloudflare dashboard:
- Log in to the Cloudflare dashboard ↗ and select your account.
- Go to Workers & Pages.
- Select your Worker > Deployments.
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 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.
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.