Create fully configured SFDX scratch orgs from existing definition files

Create fully configured SFDX scratch orgs from existing definition files

Ellis Toms on

Share with


In the age of Salesforce DX, the way we build on the Salesforce platform is changing. Part of that change includes the welcoming of scratch orgs into our development process. Scratch orgs are one of the most exciting features to come out of SFDX; they’re clean, ephemeral environments that you can spin up to build packages and test deployments ahead of time, without the worry of maintaining the environment.

Dedicated to bringing the benefits of DX to admins as well as developers, back in November we added the ability to create a scratch org in Gearset with just one click. Then more recently we released an update that allows you to choose the expiry period of your scratch orgs too, all with the ease of clicks-not-code.

But there’s always room for improvement. Creating scratch orgs and setting their expiry period is a great starting point, but there are lots more configuration options when creating a scratch org. To make this feature useful to DevOps teams, we need to support the full breadth of configuration options from Gearset’s UI, without having to touch the command line.

Gearset’s latest beta does just that, letting you create scratch orgs from any existing definition files and configure general settings, without having to resort to using the CLI. This means you can create highly tailored scratch orgs in a matter of clicks and integrate them seamlessly with Gearset’s existing comparison and deployment features.

Live eventConvene, Chicago

DevOps Dreamin’ Chicago 2024

Find out more

Using a definition file to spin up a scratch org

Gearset’s beta now allows you to spin up a scratch org based on a definition file, so you can customise your scratch org beyond name and expiry date. By using definition files, you can specify which add-on features are enabled within an org, such as Communities, CustomApps, and PersonAccounts, so you can create a scratch org that mirrors your other environments.

How does it work

To create scratch orgs within Gearset, you first need to enable and connect a Dev Hub org, which acts as a home for your scratch orgs. You can select an SFDX Dev Hub to connect to via the Scratch orgs and dev hubs page, found under My Salesforce connections on the left-hand side menu.

Once connected, you’ll be able to create and delete scratch orgs, which will all be linked to the Dev Hub until they expire. To create a new scratch org, click Define and create a new scratch org.

Once you've connected a Dev Hub, create a new scratch org.

You’ll then have the option to upload a json definition file for your scratch org, or to manually configure its parameters via the UI. If you upload a definition file, Gearset will use the json file to automatically fill in the general settings of the org for you, which you can then customize before creating your scratch org.

Coming soon you’ll also be able to to enable and disable specific org preferences, so keep your eyes peeled for more updates. For a full list of features and preferences, check out the Salesforce developer site.

To show you how this works, in the example below we’ve uploaded the dev-sfdx-definition-file.json definition file to create our scratch org from and as a result, Gearset has automatically completed the settings for us based on this file.

  "orgName": "[email protected]",
  "country": "US",
  "edition": "Developer",
  "adminEmail": "[email protected]",
  "description": "Testing scratch org with PersonAccounts enabled",
  "hasSampleData": "true",
  "features": ["MultiCurrency", "AuthorApex", "PersonAccounts"],
  "orgPreferences": {
    "enabled": ["S1DesktopEnabled", "ChatterEnabled", "CustomTabs"],
    "disabled": ["IsNameSuffixEnabled"]
Upload your definition file and Gearset will automatically fill in the settings for your new org.

Once you’re happy with your scratch org settings, hit Create scratch org and wait for your scratch org to be created. Once complete you’ll be able to Log in to scratch org, and view the org details directly within Salesforce, as shown below.

Once you've successfully created your new scratch org, you can log in with just a click.
View your new scratch org in Salesforce.

Now your new scratch org is complete you can start comparing and deploying to and from it, following the usual Gearset deployment process. Just head to the Compare and deploy page under Metadata deployments and select SFDX scratch org as either the source or target of your comparison, choose your new scratch org and continue the deployment process as usual. Simple!

You can now compare and deploy to and from your newly configured scratch org.

Future development

As this feature is in active beta, we’ll be adding more exciting functionality within the next few weeks. This will include the ability to enable (or disable) org preferences, like IsEmailTrackingEnabled, ChatterEnabled and IsEntitlementsEnabled, so stay tuned for future updates!

As always, if there’s any way you think this feature could be improved then please let us know! You can get in touch with our development team via the live chat or at [email protected].

Get started now!

SFDX scratch orgs shouldn’t be a developer-only experience. An instant clean environment makes trying out deployments, Apex code and tests easy and stress-free. With Gearset’s simple UI, we’ve lowered the barrier to entry and made scratch orgs usable for everyone, even those less comfortable with the CLI.

If you like the sound of this feature and you’re interested in trying out Gearset for yourself, you can sign up for our free 30-day trial today. There’s no credit card information required or anything to install in your orgs — just log in and get going!

And to find out more about how and when teams should adopt Salesforce DX, download our free whitepaper, Adopting Salesforce DX.

Try all of Gearset for free