Scratch Orgs

The scratch org is a source-driven and disposable deployment of Salesforce code and metadata. A scratch org is fully configurable, allowing developers to emulate different Salesforce editions with different features and settings. You can share the scratch org configuration file with other team members, so you all have the same basic org in which to do your development. In addition to code and metadata, developers can install packages and deploy synthetic or dummy data for testing. Don’t add personal data to scratch orgs.

Scratch orgs drive developer productivity and collaboration during the development process, and facilitate automated testing and continuous integration. You can use Salesforce CLI or an IDE to open your scratch org in a browser without logging in. Spin up a new scratch org when you want to:

  • Start a new project.
  • Start a new feature branch.
  • Test a new feature.
  • Start automated testing.
  • Perform development tasks directly in an org.
  • Start from “scratch” with a fresh new org.

Alternatives to scratch orgs are sandboxes and Developer Edition orgs, which are used as development environments for many Salesforce development use cases. If you’re wondering whether to use a sandbox, scratch org, or Developer Edition org as your development environment, you’re not alone. To help you better understand which to choose, see the Salesforce Developers Blog: Choose the Right Salesforce Org for the Right Job.

Source Tracking

Source tracking refers to tracking the changes you make to your local source files and the metadata in your org, and keeping both in sync.

Scratch orgs have source tracking enabled by default. You can opt out of source tracking when you create the scratch org by specifying the --no-track-source flag of the org create scratch command. This flag affects only your local configuration, not the scratch org itself. Salesforce CLI sets a local configuration option trackSource: false as part of your authorization information to the org. If you log out of the scratch org and then log back in again, source tracking is enabled again by default.

If you’re actively in development mode, we suggest keeping source tracking enabled in your scratch org so you can easily sync the changes between your org and your local project. But source tracking can slow down deployments and retrievals, so it’s sometimes better to disable it if it’s not needed. Here are some use cases.

  • Your continuous integration (CI) script simply creates a scratch org, deploys source, runs Apex and browser tests, and then deletes the scratch org.
  • You want to spin up a scratch org for a demo, user acceptance testing, or debugging.
  • Your test data has changed and you want to ensure it’s correct by importing it into a scratch org. But you haven’t changed any metadata or source code.
  • You want to install and verify a package your CI built.
  • You want to test a pull request by deploying code to a scratch org, but you don’t plan to change the code.

Scratch Org Creation Methods

By default, scratch orgs are empty. They don’t contain much of the sample metadata that you get when you sign up for an org, such as a Developer Edition org, the traditional way. Some of the things not included in a scratch org are:

  • Custom objects, fields, indexes, tabs, and entity definitions
  • Sample data
  • Sample Chatter feeds
  • Dashboards and reports
  • Workflows
  • Picklists
  • Profiles and permission sets
  • Apex classes, triggers, and pages

Before creating a scratch org, you must configure it so it has the features, settings, licenses, and limits that mirror a source org, often your production org. The combination of features, settings, edition, licenses, and limits are what we refer to as the org’s shape.

We offer these methods for configuring scratch orgs:

On Which Salesforce Instances Are Scratch Orgs Created?

Scratch orgs are created on sandbox instances. The sandbox instance depends on the country information used when creating the Dev Hub org.

Scratch orgs for Government Cloud and Hyperforce are created in the region where the Dev Hub org is physically located.

  • Scratch orgs created from a Dev Hub org in Government Cloud are created in a Government Cloud instance.
  • Scratch orgs created from a Dev Hub org in Hyperforce are created on a Hyperforce instance.

If you notice that your scratch orgs aren’t located in the expected region, create a Salesforce Support case.

Scratch Org Expiration Policy

A scratch org is temporary and is deleted along with the associated ActiveScratchOrgs records from the Dev Hub after their expiration. This expiration process ensures that teams frequently sync their changes with their version control system and are working with the most recent version of their project.

Scratch orgs have a maximum 30 days lifespan. You can select a duration from 1 through 30 days at the time of creation, with the default set at 7 days. After the scratch org has expired, you can’t restore it.

Deleting a scratch org doesn’t terminate your scratch org subscription. If your subscription is still active, you can create a new scratch org. Creating a new scratch org counts against your daily and active scratch org limits.

Note