Contact sales: +1 (833) 441 7687

Automate the creation of Salesforce scratch orgs within a continuous integration (CI) workflow

Jonathan Plumridge on July 14th 2020

Modern SFDX workflows often rely heavily on the use of scratch orgs, which are a great tool for testing changes in a safe environment. Gearset supports both manual creation of scratch orgs, as well as automatic creation during continuous integration (CI) jobs, which is what we'll focus on in this post.

What are scratch orgs good for?

Scratch orgs are temporary environments that you can spin up to do development work in isolation, build and test deployment packages ahead of time, or just 'fiddle around with stuff' without the worry of maintaining the environment. For example, you might create a scratch org based on the metadata in your version control system (VCS), then get on with development work without worrying about stepping on your team members' toes.

Typically, scratch orgs are created using the SFDX command line interface (CLI). This is where things can quickly get complicated, as there are lots of tricky commands and options to remember. Switching between different Dev Hubs can also be a hassle sometimes, especially if you forget which Dev Hub username has been set as default, as this can lead to someone accidentally making changes to the wrong Dev Hub. We decided to make things a bit easier for Gearset users.

Get your CI job in Gearset to create a scratch org

Continuous integration jobs that allow for automatic validation or deployment of metadata are one of Gearset's core features. Whenever possible, we encourage the use of CI to enhance development workflows, as we think it's one of the best ways we can help people on their DevOps journey.

Whether you're using CI to automatically validate a package built from a Git source, or using it to regularly deploy between two Salesforce environments, CI can really accelerate your development process. We already know that utilizing CI in your process can have a dramatic measurable impact - we found that teams using CI deploy 17 times more frequently than teams that don't, and have a success rate of more than 90% when deploying to production.

One of Gearset's more advanced features lets you automatically create a scratch org in a Dev Hub of your choice from your CI job, and use it as the target of your deployment or validation. When your CI deployment source is a Git repo in SFDX source format, and your target is a new scratch org, your CI job will automatically create a scratch org based on the scratch-def.json configuration, using the namespace found in the sfdx-project.json file. It will also install the package dependencies listed in sfdx-project.json.

Sample sfdx-project.json file:

  "packageDirectories": [
      "path": "force-app",
      "default": true,
      "package": "MyUnlockedPackage",
      "versionName": "ver 2.3",
      "versionNumber": "2.3.7.NEXT",
      "dependencies": [
           "package": "[email protected]"
           "package": "[email protected]"
  "namespace": "NSNS",
  "sourceApiVersion": "45.0",
  "packageAliases": {
    "[email protected]": "04t3u000013X3cuAAC",
    "[email protected]": "04t4d070013X4cuAAC",
    "MyUnlockedPackage": "0Ho4J000000XZnkSAG",
    "[email protected]": "04t4J0000035bZ4QAI"

Sample scratch-def.json file:

  "orgName": "TestScratchOrgForCI",
  "country": "GB",
  "adminEmail": "[email protected]",
  "edition": "Developer",
  "description": "This is a scratch org to test CI deployments",
  "hasSampleData": false,
  "features": [

Here you can see how easy it is to create a CI deployment job in Gearset that targets a scratch org:

Add a CI deployment job in Gearset

Example use case

The following is an example of using CI to streamline your development process and build better confidence in the resulting managed package.

Suppose I'm developing a managed package, for which I'm using Git to source control my metadata and Apex code, with feature branches that I merge into master via pull requests (PRs).

My development process looks something like this:

  1. Use Gearset to deploy from my Git repo (master branch) to a scratch org created from the Gearset deployment UI.
  2. Do my development work in the safe environment of my new scratch org.
  3. Use Gearset to manually deploy from my scratch org containing my work into a feature branch.
  4. Use Gearset to create a PR between my feature branch and master, then review and merge from the Github UI (or from the equivalent UI of the Git hosting provider you're using).

Once I've run through these steps, I need to validate that the package I have in Git is working, and safe to deploy back into my development or QA org, before releasing a version of my package to production. This might just be to make sure I have a valid source of truth in Git for my package, or it might be because, when I deployed from my scratch org to Git, I was selective with what metadata I deployed. Or, maybe, I just wanted to take advantage of Gearset's problem analyzers to check the package can be deployed, or make use of Gearset's repo cleaner to clean up any obsolete metadata in my repo. As long as I've created a CI job that targets a scratch org, with a Git repo source where I've configured an incoming webhook for merged PRs, this is where Gearset takes over:

  1. An incoming webhook triggers a CI job in Gearset when a PR is merged.
  2. The CI job automatically creates a new scratch org based on the scratch-def.json configuration, and the package dependencies and namespace found in the sfdx-project.json file.
  3. The CI job then takes the metadata in my repo, and validates/deploys it to the newly created scratch org

Now, I've validated that my package in source control is safe to use and passes all my Apex tests, etc. Automated success!

CI job success with scratch org

Does your CI process include scratch orgs?

As with many of the improvements we make to Gearset, using scratch orgs within the CI workflow started with a user request. Where DevOps workflows are concerned, we're always really interested to know about your process, to see how we can support or improve upon it for you. If you have an improvement to suggest, or feature request you'd like to make, get in touch using the in-app chat, or head to our feedback forum. Keep those suggestions coming, we're always happy to hear from you!

Ready to get started with Gearset?

Start free trial