preference-rollout: Permanently Change a Preference

The preference-rollout action permanently changes a preference in order to deploy a proven feature to most or all users of Firefox.

Users who match preference-rollout have values changed to match the configuration of the recipe. While the change is active, Telemetry pings are annotated to note that the rollout is changing a value to a non-default value. This allows us to measure the effect the preference change has on existing Telemetry metrics.

Preference rollout works by changing the value of the preferences on the default preference branch. Since changes to the default branch are not persistent, this process must be repeated every time Firefox starts. This process continues until a rollout is rolled back or until it graduates.

Rollouts do not support branching, and are intended to be permanent. If there is a mistake, a rollback can be undone with a preference-rollback action.


Users may be enrolled in multiple preference rollouts at the same time.


Preference experiments are designed to be permanent. They are not appropriate for temporary changes.

Telemetry Annotation

While an experiment is running, the Telemetry Environment contains a list of “experiment” IDs. This field is also used to mark other non-default changes, such as rollouts. The Telemetry environment is sent along with the main ping, among others.

  "environment": {
    "experiments": {
      "<rollout id>": { "branch": "<branch>" },


Rollouts expect that eventually the value of the preference built in to Firefox will change to match the value of the rollout. This generally happens when Firefox updates to a new version that has the preferences updated. When this happens, the preference rollout graduates. Once a rollout graduates, it stops setting the value of the preference at startup. If the default value then changes again, Normandy will not change it back to the rollout value.



A unique identifier for this rollout. This is used for server and telemetry identification of the rollout.


A list of preferences to change, each with the following arguments:


The full dotted-path of the preference to modify.


The type of the preference to modify. If this doesn’t match the type on the client, the rollout will not apply to anyone.


Value to set the preference to for users that are assigned to this branch.