Select the Salesforce Release for a Scratch Org

What Is Salesforce Preview?

During every major Salesforce release, you can get early access to the upcoming release in your scratch orgs and sandboxes to test new customizations and features before your production org is upgraded. This window is called the Salesforce Preview, and scratch orgs created on the upcoming release are called preview scratch orgs.

Normally, you create scratch orgs that are the same version as the Dev Hub. However, during the major Salesforce release transition that happens three times a year, you can select the Salesforce release version Preview or Previous, based on the version of your Dev Hub.

To try out new features in an upcoming release, you no longer have to create a trial Dev Hub on the upcoming version to create preview scratch orgs. You can use your existing Dev Hub that includes your existing scratch org active and daily limits.

For example, you can select a version over the next three releases during these release transition dates. Preview start date is when sandbox instances are upgraded. Preview end date is when all instances are on the GA release.

Because previous and preview are relative terms, your Dev Hub org version during the release transition determines their relative significance. Here’s what happens when you try to create a scratch org with one of the release values.

Create a Scratch Org for a Specific Release

You can specify the release version in the scratch org definition file or directly on the command line. Any value you set on the command line overrides what you have defined in your scratch definition file.

• Find out which instance your Dev Hub org is on: https://status.salesforce.com.
• Add the release option (lowercase) to your scratch org definition file.
  1{
  2   "orgName": "Dreamhouse",
  3   "edition": "Developer",
  4   "release": "preview",
  5   "settings": {      
  6      "mobileSettings": {
  7          "enableS1EncryptedStoragePref2": true
  8      }
  9   }
  10}

  Alternatively, you can specify the release value directly on the command line with the --release flag. Any value you specify on the command line overrides the value in the scratch org definition.

• Create the scratch org by executing the org create scratch command in a terminal (macOS and Linux) or command prompt (Windows).

  In this example, we’re creating a scratch org on the preview release.

  1sf org create scratch --definition-file config/project-scratch-def.json --alias PreviewOrg --target-dev-hub DevHub --release preview

Be sure to set the apiVersion to match the scratch org version.

To set it globally for all DX projects:

1sf config set org-api-version 59.0 --global

To set it on the command line:

1SF_ORG_API_VERSION=59.0 sf org create scratch  --definition-file config/project-scratch-def.json --alias PreviewOrg --target-dev-hub DevHub --release preview

What If I Want to Create a Pre-Release Scratch Org?

Pre-release is a very early build of the latest version of Salesforce that’s available before Salesforce Preview. It's not built to handle scale and doesn't come with any Salesforce Support service-level agreements (SLAs). For this reason, the only way to create a pre-release scratch org is to sign up for a pre-release trial Dev Hub org (subject to availability).