Cloudflare Docs
Version Management
Visit Version Management on GitHub
Set theme to dark (⇧+D)

Get started

Follow this tutorial to start testing and deploying zone configuration changes with Version Management.

​​ Step 1 - Enable versioning

By default, Version Management is not enabled on a zone.

To enable Version Management:

  1. Log in to the Cloudflare dashboard.
  2. Select your account and zone.
  3. Go to Version Management.
  4. Select Enable versioning.

​​ Step 2 (optional) - Create additional environments

Once you enable Version Management, Cloudflare will automatically create:

  • Version Zero, think about this as the configurations of your current zone. Part of your products currently visible in the navigation are going to be displayed under Versions and the other ones under Global Settings. Once default environments are created, Version Zero is automatically deployed to them, guaranteeing no disruption in your live traffic. This Version is also permanently editable. In case you decide to disable Zone Versioning, Version Zero will become your zone again.
  • Global Settings, you can find all the settings here that are not supported by Version Management.

On the Environments page, you can create default environments for Production, Staging, and Development.

These environments each serve a specific purpose and are accessed differently:

  • Development: Meant to validate that changes work correctly. The default traffic filters are that the cf.zone.name matches your zone name, the Edge Server IP is a specific value, and the request contains a cookie with development=true.
  • Staging: Meant to test changes before sending them to Production. The default traffic filters are that the cf.zone.name matches your zone name and the Edge Server IP is a specific value.
  • Production: Meant to hold all settings applied to your zone. You cannot edit the traffic filters - which are just that the cf.zone.name is equal to your zone’s name - and cannot delete this environment. This environment has a read-only check enabled, so versions promoted to this environment will become read-only as well.

Based on your organization’s needs, you may need to create additional environments to test and roll out changes.

For more details, refer to Create environment.

​​ Step 3 - Update settings

Before making changes, make sure you are inside the correct version of your zone.

To change between different versions of your zone:

  1. Log in to the Cloudflare dashboard.
  2. Select your account and zone.
  3. Go to Version Management.
  4. On a specific version, select Select.

You can also change which version you are in from any page by using the sidebar dropdown.

Select a version from the Versions page or the sidebar dropdown

From within a version, you can update settings just as you would with your normal zone settings. Any changes are saved automatically.


​​ Step 4 - Test version

Once you have made changes to a version, apply that version to your lowest-ranked environment.

  1. Log in to the Cloudflare dashboard.
  2. Select your account and zone.
  3. Go to Version Management.
  4. Go to Environments.
  5. On your lowest-ranked environment, use the Version dropdown to select your desired version.

To test your version, send requests to that environment that match the pattern specified in its traffic filters.

For more details about what happens to these requests, refer to the version’s metrics.

​​ Step 5 - Promote version

Next, promote your version through your different environments.

To promote a version:

  1. Log in to the Cloudflare dashboard.
  2. Select your account and zone.
  3. Go to Version Management.
  4. Select Environments.
  5. On the environment in which you tested the version, select Promote. This option will only be available if the lower-ranked environment has a different version than the higher-ranked environment.

Promoting a version to a read-only environment will make the version permanently read-only.

After promoting to each environment, test the new version in your new environment.

​​ Step 6 - Repeat

For new changes to your zone, create a new version and repeat this process.