How to select the Salesforce release for a Scratch Org
Tags: salesforce, sfdx, release
Published: 2019-07-29 19:52:14

---
title: How to select the Salesforce release for a Scratch Org
published: true
description: 
tags: salesforce, sfdx, release
cover_image: https://matheusgoncalves.com/wp-content/uploads/2019/07/previewOrgs.jpg
---

Did you know you can specify the release (preview or previous) when creating a scratch org?

That is especially helpful when testing your code against future features in Preview orgs, [but it’s even more than that](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_scratch_orgs_version_selection.htm):

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

This way you not only can try out new features in an upcoming release, to check if they **will fit your needs** but also by running your applications in preview orgs, you can **proactively** check if your code is in good shape or if there will be a **breaking change**.

Then you can add any future bug to your backlog and plan your work accordingly, with fewer surprises.

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.

Before this change, you would have to create a trial Dev Hub on the upcoming version to create preview scratch orgs. Now you can use your existing Dev Hub that includes your existing scratch org active and daily limits.

Because previous and preview are all 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.

<table>
    <tr>
        <td><strong>Dev Hub Version</strong></td>
        <td><strong>Preview </strong></td>
        <td><strong> Previous </strong></td>        
    </tr>
    <tr>
        <td>Dev Hub has upgraded to the latest version</td>
        <td>Error (Dev Hub is already on the latest version)</td>
        <td>Prior Dev Hub version</td>
    </tr>
    <tr>
        <td>Dev Hub is still on the GA version</td>
        <td>Version following the Dev Hub version (newly released Salesforce version)</td>
        <td>Error (Dev Hub is on the GA version; previous version unavailable)</td>
    </tr>
</table>

Important note: If you don’t specify a release value, the scratch org version is the same as the Dev Hub org.

### 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 option you issue on the command line overrides what you have defined in your scratch definition file.

Find out which instance your Dev Hub org is on: [status.salesforce.com](https://status.salesforce.com/).
Add the release option to your [scratch org definition file](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_scratch_orgs_def_file_config_values.htm):

{% gist https://gist.github.com/toadgeek/73731a1ca29ad5a8b78ed068c382fc66 %}

If you’re planning on using some sort of script to spin up a new scratch org, or you just prefer using the command line, you can specify the release value directly on the CLI!

Please note the use of the release keyword: release=Preview

{% gist https://gist.github.com/toadgeek/9ddf75450df0b933dc2a6e9ff465c173 %}


If you’re creating a previous scratch org and you have upgraded the CLI to the pre-release version, be sure to set the apiVersion to match the scratch org version.

To set it globally for all DX projects:

{% gist https://gist.github.com/toadgeek/ea7d6a9d5f2471e3fd4906e4cd21a791 %}

To set it on the command line:

{% gist https://gist.github.com/toadgeek/c77dec41bd7def1b39ab6758d5c60134 %}


### 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](https://sfdc.co/RR-Pre-Release) (subject to availability).

This article was originally published in [matheus.dev](https://matheusgoncalves.com/how-to-select-the-salesforce-release-for-a-scratch-org/).