Skip to main content


Optimizely Knowledge Base

Use environments to QA your experiment code

  • Use environments to test and QA your experiment code before deploying it
  • Explore use cases for Optimizely environments
  • Run your experiment code in different environments
  • Manage your environments

Optimizely environments allow you to organize your projects into logical sections that correspond to your development environments. Doing so allows you to view and test your experiment code before you deploy it to your application. Whether or not you already use a formal deployment environment, you can create environments to ensure the quality of your experiment code in an independent setting before you show it to visitors.

Essentially, Optimizely environments allows a single experiment to be running in some contexts and paused in others. You can turn an experiment on and run it for your team so they can test it, but leave it turned off for visitors. Environments enable you to do this without duplicating your code, Optimizely project, or experiments within your project.

Environments are currently available only for Optimizely X Full Stack projects.

How environments work

Every Optimizely project starts with one environment (and one datafile) named Production. When you set up an environment, Optimizely generates a corresponding datafile. The datafiles generated by these additional environments represent the current states of all experiments within your Optimizely project. Each environment-specific datafile represents only the state of the experiments within that environment.

For example, imagine you have three experiments: sort-by-name, show-subtotal, and warn-empty-cart. You set up a new environment named Testing so you can test your experiment code before you deploy in the Production environment. Suppose that:

  • You completed testing for the sort-by-name experiment and deployed it.

  • You are currently testing the show-subtotal experiment.

  • Your warn-empty-cart experiment has been tested but is not yet deployed.

Here’s an overview of the statuses of your three experiments in your two environments:


Testing environment activity state and datafile status

Production environment activity state and datafile status






Not started



Not started

*You can keep experiments running in your testing environment that are also running in production if you prefer.

Now, let’s imagine that the project owner creates a third environment: Development. Optimizely will generate an additional datafile named Development. Every experiment will be in the “Not started” activity state in Development, and the Development datafile will show experiment status as “Not started.”

When your experiment code is fully functional and ready to test, switch it to the Testing environment by pointing your code to the Testing datafile.

SDK keys and environment keys

For each environment, Optimizely generates a unique SDK key. The key determines the URL of the environment's datafile, which ensures that the URL won’t be easily guessed. For SDKs that provide native datafile managers (currently iOS, tvOS, and Android), you can use the SDK key to initialize the SDK with with the corresponding environment's datafile.

When you create an environment, you will also be asked to provide an environment key. This key is used for programmatic access to the environment: for example, if you were to modify your environments using Optimizely's REST API.

Environments and security

Improve security by restricting permissions for starting and stopping experiments in an environment to collaborators with Publisher permissions. This limits the number of people who can change your experiments’ statuses or move them from one environment to another.

We recommend keeping access open to everyone in local or development environments and restricting access in production environments. By default, the production environment is limited to Publishers and above, which is the same permission level that applies if you aren’t using the environments feature.

Use cases for environments

Here are two examples of environments use cases. You can have an unlimited number of environments, and there are many more possibilities for using them than we have described here. Use as many environments as your workflow requires. 

In general, the fewer environments you use, the simpler the workflow. If you use two or more environments, they’ll be grouped together on your experiment list as “Other Environments.”

Three-stage testing

The three-stage testing use case involves these separate, sequential environments:

  • Local: code is running only for the developer who is writing it. You don’t need to create a separate Local environment for each developer, just one environment where the experiment will run during development.

  • Staging: code is shared with the larger development team and QA.

  • Production: code is deployed and running for all visitors.

Two-stage “sandbox” QA

The two-stage “sandbox” QA use case is a common setup in web development and involves these separate, sequential environments:

  • Local: code is running only for the development team and QA

  • Production: code is deployed and running for all visitors

You can use the "sandbox" approach even if you don’t have separate deployment environments for your application. One common use case is to toggle between the local and production files for debugging. For example, you could load the local file when a certain “test” cookie is enabled, when a certain URL parameter is attached (like ?debug=true), or based on some other check that matches your internal workflow.

Create environments

By default, every project starts with a single default environment with a single datafile inside it that includes everything from the project. You can rename the default environment and add more environments as needed. Here's how to create an environment, with step-by-step instructions below.


  1. Navigate to Settings > Datafile.

  2. Click New Environment…

  3. Enter the environment name, key, and optional description. Specify the permission level you want to set for experiments in the environment.

  4. Click Create Environment and Datafile.

  5. Implement the datafile in your application.
    Learn more about accessing the datafile and best practices for datafile management.

Experiments are paused by default in any new environments you create, even if they were already running in the default environment.

Change experiment status in an environment

When you use multiple environments for a project, experiment status is no longer either “Running” or “Paused” on the Experiments dashboard. Instead, each experiment’s status will be specified with icons that represent the state of the experiment in each environment:


To change an experiment’s status in an environment:

  1. Click the icon for the experiment.

  2. Select Run or Pause for the environment where you want to change the experiment’s status.

Learn how to designate which environment is shown to visitors in our article about best practices for datafile management.

Rename an environment

To rename an environment:


  1. Navigate to Settings > Datafile.

  2. Click the icon for the environment you want to rename.

  3. Click Settings.

  4. Enter the new name for the environment and click Save Environment.

Archive an environment

You can archive environments if they aren’t being used anymore (except the primary environment, which can't be archived). Archiving deactivates all the datafiles in an environment, replacing them with an empty file, and removes the environment as an option for experiments.

If experiments are running in the environment when you archive it, they will stop because archiving empties the datafile.

To archive an environment:


  1. Navigate to Settings > Datafile.

  2. Click the icon for the environment you want to archive.

  3. Click Archive.

Results by environment

As you build, launch, and promote your experiments from lower level environments into production, you will want to differentiate between results that were triggered during your QA process and results that were triggered by live users. To do so, we recommend that you create an attribute for environments, then set the attribute's value with the environment from which an event is sent. This will allow you to use segmentation to filter your results by this attribute.